From f56d8c47842702c5af19ee28aa5d3ee8c6bc2be9 Mon Sep 17 00:00:00 2001 From: yangxiao Date: Mon, 16 Mar 2015 15:31:29 +0800 Subject: [PATCH 01/32] fix camra mask for label does not work --- cocos/2d/CCLabel.cpp | 12 ++++++++++++ cocos/2d/CCLabel.h | 2 ++ 2 files changed, 14 insertions(+) diff --git a/cocos/2d/CCLabel.cpp b/cocos/2d/CCLabel.cpp index b9d991555f..3058be1c4b 100644 --- a/cocos/2d/CCLabel.cpp +++ b/cocos/2d/CCLabel.cpp @@ -910,6 +910,18 @@ void Label::draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) } } +void Label::setCameraMask(unsigned short mask, bool applyChildren) +{ + if (_textSprite) + { + _textSprite->setCameraMask(mask, applyChildren); + } + if (_shadowNode) + { + _shadowNode->setCameraMask(mask, applyChildren); + } +} + void Label::createSpriteWithFontDefinition() { _currentLabelType = LabelType::STRING_TEXTURE; diff --git a/cocos/2d/CCLabel.h b/cocos/2d/CCLabel.h index e6d7c4715b..0fe7246f98 100644 --- a/cocos/2d/CCLabel.h +++ b/cocos/2d/CCLabel.h @@ -266,6 +266,8 @@ public: virtual void visit(Renderer *renderer, const Mat4 &parentTransform, uint32_t parentFlags) override; virtual void draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) override; + virtual void setCameraMask(unsigned short mask, bool applyChildren) override; + CC_DEPRECATED_ATTRIBUTE static Label* create(const std::string& text, const std::string& font, float fontSize, const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT, TextVAlignment vAlignment = TextVAlignment::TOP); From 5b26ba3c68082b98e601e4622bf67485318c4d4b Mon Sep 17 00:00:00 2001 From: yangxiao Date: Mon, 16 Mar 2015 17:11:17 +0800 Subject: [PATCH 02/32] override setCameraMask --- cocos/2d/CCClippingNode.cpp | 8 ++++++++ cocos/2d/CCClippingNode.h | 2 ++ cocos/2d/CCLabel.cpp | 2 ++ cocos/2d/CCLabel.h | 2 +- 4 files changed, 13 insertions(+), 1 deletion(-) diff --git a/cocos/2d/CCClippingNode.cpp b/cocos/2d/CCClippingNode.cpp index de31dba134..9c17a372b7 100644 --- a/cocos/2d/CCClippingNode.cpp +++ b/cocos/2d/CCClippingNode.cpp @@ -316,6 +316,14 @@ void ClippingNode::visit(Renderer *renderer, const Mat4 &parentTransform, uint32 director->popMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW); } +void ClippingNode::setCameraMask(unsigned short mask, bool applyChildren) +{ + Node::setCameraMask(mask, applyChildren); + + if (_stencil) + _stencil->setCameraMask(mask, applyChildren); +} + Node* ClippingNode::getStencil() const { return _stencil; diff --git a/cocos/2d/CCClippingNode.h b/cocos/2d/CCClippingNode.h index 9700681638..51c44b46e5 100644 --- a/cocos/2d/CCClippingNode.h +++ b/cocos/2d/CCClippingNode.h @@ -104,6 +104,8 @@ public: virtual void onExit() override; virtual void visit(Renderer *renderer, const Mat4 &parentTransform, uint32_t parentFlags) override; + virtual void setCameraMask(unsigned short mask, bool applyChildren = true) override; + CC_CONSTRUCTOR_ACCESS: ClippingNode(); diff --git a/cocos/2d/CCLabel.cpp b/cocos/2d/CCLabel.cpp index 3058be1c4b..3c60b2dce6 100644 --- a/cocos/2d/CCLabel.cpp +++ b/cocos/2d/CCLabel.cpp @@ -912,6 +912,8 @@ void Label::draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) void Label::setCameraMask(unsigned short mask, bool applyChildren) { + SpriteBatchNode::setCameraMask(mask, applyChildren); + if (_textSprite) { _textSprite->setCameraMask(mask, applyChildren); diff --git a/cocos/2d/CCLabel.h b/cocos/2d/CCLabel.h index 0fe7246f98..c62f2e0a34 100644 --- a/cocos/2d/CCLabel.h +++ b/cocos/2d/CCLabel.h @@ -266,7 +266,7 @@ public: virtual void visit(Renderer *renderer, const Mat4 &parentTransform, uint32_t parentFlags) override; virtual void draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) override; - virtual void setCameraMask(unsigned short mask, bool applyChildren) override; + virtual void setCameraMask(unsigned short mask, bool applyChildren = true) override; CC_DEPRECATED_ATTRIBUTE static Label* create(const std::string& text, const std::string& font, float fontSize, const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT, From 8b3e116ed6f1373e3b42f06ec7999393fb257d0e Mon Sep 17 00:00:00 2001 From: yangxiao Date: Mon, 16 Mar 2015 18:04:50 +0800 Subject: [PATCH 03/32] check running scene --- cocos/3d/CCSprite3D.cpp | 20 ++++++++++++-------- cocos/renderer/CCMeshCommand.cpp | 6 ++++-- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/cocos/3d/CCSprite3D.cpp b/cocos/3d/CCSprite3D.cpp index 7000acb58c..a20be76a4f 100644 --- a/cocos/3d/CCSprite3D.cpp +++ b/cocos/3d/CCSprite3D.cpp @@ -687,15 +687,19 @@ void Sprite3D::draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) color.a = getDisplayedOpacity() / 255.0f; //check light and determine the shader used - const auto& lights = Director::getInstance()->getRunningScene()->getLights(); - bool usingLight = false; - for (const auto light : lights) { - usingLight = ((unsigned int)light->getLightFlag() & _lightMask) > 0; - if (usingLight) - break; + const auto& scene = Director::getInstance()->getRunningScene(); + if (scene) + { + const auto& lights = scene->getLights(); + bool usingLight = false; + for (const auto light : lights) { + usingLight = ((unsigned int)light->getLightFlag() & _lightMask) > 0; + if (usingLight) + break; + } + if (usingLight != _shaderUsingLight) + genGLProgramState(usingLight); } - if (usingLight != _shaderUsingLight) - genGLProgramState(usingLight); int i = 0; for (auto& mesh : _meshes) { diff --git a/cocos/renderer/CCMeshCommand.cpp b/cocos/renderer/CCMeshCommand.cpp index cb357611b7..a8e8b4bde9 100644 --- a/cocos/renderer/CCMeshCommand.cpp +++ b/cocos/renderer/CCMeshCommand.cpp @@ -297,7 +297,8 @@ void MeshCommand::batchDraw() _glProgramState->applyGLProgram(_mv); _glProgramState->applyUniforms(); - if (Director::getInstance()->getRunningScene()->getLights().size() > 0) + const auto& scene = Director::getInstance()->getRunningScene(); + if (scene && scene->getLights().size() > 0) setLightUniforms(); // Draw @@ -339,7 +340,8 @@ void MeshCommand::execute() _glProgramState->apply(_mv); - if (Director::getInstance()->getRunningScene()->getLights().size() > 0) + const auto& scene = Director::getInstance()->getRunningScene(); + if (scene && scene->getLights().size() > 0) setLightUniforms(); glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, _indexBuffer); From 080132d0720f6ddf06f6b1bc65a1f4cd1ca30ae4 Mon Sep 17 00:00:00 2001 From: lvlong Date: Tue, 17 Mar 2015 12:15:03 +0800 Subject: [PATCH 04/32] modify sub node transform! --- cocos/3d/CCSprite3D.cpp | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/cocos/3d/CCSprite3D.cpp b/cocos/3d/CCSprite3D.cpp index a20be76a4f..42c83babdb 100644 --- a/cocos/3d/CCSprite3D.cpp +++ b/cocos/3d/CCSprite3D.cpp @@ -370,7 +370,22 @@ Sprite3D* Sprite3D::createSprite3DNode(NodeData* nodedata,ModelData* modeldata,c } } } - sprite->setAdditionalTransform(&nodedata->transform); + //sprite->setAdditionalTransform(&nodedata->transform); + Vec3 pos; + nodedata->transform.getTranslation(&pos); + + Quaternion qua; + nodedata->transform.getRotation(&qua); + + Vec3 scale; + nodedata->transform.getScale(&scale); + + sprite->setPosition3D(pos); + sprite->setRotationQuat(qua); + sprite->setScaleX(scale.x); + sprite->setScaleY(scale.y); + sprite->setScaleZ(scale.z); + sprite->addMesh(mesh); sprite->autorelease(); sprite->genGLProgramState(); @@ -527,7 +542,22 @@ void Sprite3D::createNode(NodeData* nodedata, Node* root, const MaterialDatas& m if(node) { node->setName(nodedata->id); - node->setAdditionalTransform(&nodedata->transform); + //node->setAdditionalTransform(&nodedata->transform); + + Vec3 pos; + nodedata->transform.getTranslation(&pos); + + Quaternion qua; + nodedata->transform.getRotation(&qua); + + Vec3 scale; + nodedata->transform.getScale(&scale); + + node->setPosition3D(pos); + node->setRotationQuat(qua); + node->setScaleX(scale.x); + node->setScaleY(scale.y); + node->setScaleZ(scale.z); if(root) { root->addChild(node); From 733a89100e53d763adfb0722832cf7d37ddff905 Mon Sep 17 00:00:00 2001 From: lvlong Date: Tue, 17 Mar 2015 13:13:03 +0800 Subject: [PATCH 05/32] remove old code! --- cocos/3d/CCSprite3D.cpp | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/cocos/3d/CCSprite3D.cpp b/cocos/3d/CCSprite3D.cpp index 42c83babdb..5cb2cc8921 100644 --- a/cocos/3d/CCSprite3D.cpp +++ b/cocos/3d/CCSprite3D.cpp @@ -370,16 +370,14 @@ Sprite3D* Sprite3D::createSprite3DNode(NodeData* nodedata,ModelData* modeldata,c } } } - //sprite->setAdditionalTransform(&nodedata->transform); + + // set locale transform Vec3 pos; nodedata->transform.getTranslation(&pos); - Quaternion qua; nodedata->transform.getRotation(&qua); - Vec3 scale; nodedata->transform.getScale(&scale); - sprite->setPosition3D(pos); sprite->setRotationQuat(qua); sprite->setScaleX(scale.x); @@ -542,22 +540,20 @@ void Sprite3D::createNode(NodeData* nodedata, Node* root, const MaterialDatas& m if(node) { node->setName(nodedata->id); - //node->setAdditionalTransform(&nodedata->transform); + // set locale transform Vec3 pos; nodedata->transform.getTranslation(&pos); - Quaternion qua; nodedata->transform.getRotation(&qua); - Vec3 scale; nodedata->transform.getScale(&scale); - node->setPosition3D(pos); node->setRotationQuat(qua); node->setScaleX(scale.x); node->setScaleY(scale.y); node->setScaleZ(scale.z); + if(root) { root->addChild(node); From 3ce0449c97f6dd4ac26b2467bcf634703b6f5c96 Mon Sep 17 00:00:00 2001 From: lvlong Date: Tue, 17 Mar 2015 15:17:23 +0800 Subject: [PATCH 06/32] decompose --- cocos/3d/CCSprite3D.cpp | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/cocos/3d/CCSprite3D.cpp b/cocos/3d/CCSprite3D.cpp index 5cb2cc8921..f5f482d60c 100644 --- a/cocos/3d/CCSprite3D.cpp +++ b/cocos/3d/CCSprite3D.cpp @@ -373,11 +373,9 @@ Sprite3D* Sprite3D::createSprite3DNode(NodeData* nodedata,ModelData* modeldata,c // set locale transform Vec3 pos; - nodedata->transform.getTranslation(&pos); Quaternion qua; - nodedata->transform.getRotation(&qua); Vec3 scale; - nodedata->transform.getScale(&scale); + nodedata->transform.decompose(&scale, &qua, &pos); sprite->setPosition3D(pos); sprite->setRotationQuat(qua); sprite->setScaleX(scale.x); @@ -543,11 +541,9 @@ void Sprite3D::createNode(NodeData* nodedata, Node* root, const MaterialDatas& m // set locale transform Vec3 pos; - nodedata->transform.getTranslation(&pos); Quaternion qua; - nodedata->transform.getRotation(&qua); Vec3 scale; - nodedata->transform.getScale(&scale); + nodedata->transform.decompose(&scale, &qua, &pos); node->setPosition3D(pos); node->setRotationQuat(qua); node->setScaleX(scale.x); From 73caf536da033b354b4884b021675731892dae74 Mon Sep 17 00:00:00 2001 From: songchengjiang Date: Tue, 17 Mar 2015 16:43:08 +0800 Subject: [PATCH 07/32] fix the bug of lighting shader --- cocos/renderer/ccShader_3D_ColorNormal.frag | 1 + cocos/renderer/ccShader_3D_ColorNormalTex.frag | 1 + 2 files changed, 2 insertions(+) diff --git a/cocos/renderer/ccShader_3D_ColorNormal.frag b/cocos/renderer/ccShader_3D_ColorNormal.frag index 6ed705a948..688dd20bc6 100644 --- a/cocos/renderer/ccShader_3D_ColorNormal.frag +++ b/cocos/renderer/ccShader_3D_ColorNormal.frag @@ -98,6 +98,7 @@ void main(void) // Apply spot attenuation attenuation *= smoothstep(u_SpotLightSourceOuterAngleCos[i], u_SpotLightSourceInnerAngleCos[i], spotCurrentAngleCos); + attenuation = clamp(attenuation, 0.0, 1.0); combinedColor.xyz += computeLighting(normal, vertexToSpotLightDirection, u_SpotLightSourceColor[i], attenuation); } \n#endif\n diff --git a/cocos/renderer/ccShader_3D_ColorNormalTex.frag b/cocos/renderer/ccShader_3D_ColorNormalTex.frag index 73f6a5fa47..e2b85042d6 100644 --- a/cocos/renderer/ccShader_3D_ColorNormalTex.frag +++ b/cocos/renderer/ccShader_3D_ColorNormalTex.frag @@ -98,6 +98,7 @@ void main(void) // Apply spot attenuation attenuation *= smoothstep(u_SpotLightSourceOuterAngleCos[i], u_SpotLightSourceInnerAngleCos[i], spotCurrentAngleCos); + attenuation = clamp(attenuation, 0.0, 1.0); combinedColor.xyz += computeLighting(normal, vertexToSpotLightDirection, u_SpotLightSourceColor[i], attenuation); } \n#endif\n From dced8004e128142b7d4378725f6da50edbe32ed9 Mon Sep 17 00:00:00 2001 From: yangxiao Date: Tue, 17 Mar 2015 17:44:52 +0800 Subject: [PATCH 08/32] reset explosion and fix bug of event handler --- .../Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp | 2 +- tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp b/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp index c1b0d17cbc..14d86176c8 100644 --- a/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp +++ b/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp @@ -80,7 +80,7 @@ void PUDoPlacementParticleEventHandler::handle (PUParticleSystem3D* particleSyst auto children = parentSystem->getChildren(); for(auto iter : children) { - PUParticleSystem3D *child = static_cast(iter); + PUParticleSystem3D *child = dynamic_cast(iter); if (child){ system = child; emitter = system->getEmitter(_forceEmitterName); diff --git a/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu b/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu index 092a2b8ad4..c5d22ef813 100644 --- a/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu +++ b/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu @@ -156,4 +156,4 @@ system explosionSystem on_time greater_than 0.3 } } -} +} \ No newline at end of file From e6770909f2825b5bd8aae5cac62829fd9f859eaa Mon Sep 17 00:00:00 2001 From: yangxiao Date: Tue, 17 Mar 2015 17:47:53 +0800 Subject: [PATCH 09/32] reset expolosion --- tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu b/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu index c5d22ef813..092a2b8ad4 100644 --- a/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu +++ b/tests/cpp-tests/Resources/Particle3D/scripts/explosionSystem.pu @@ -156,4 +156,4 @@ system explosionSystem on_time greater_than 0.3 } } -} \ No newline at end of file +} From a9e5f8cc4a5cdf7b0a1d582bfbf648fe30295eee Mon Sep 17 00:00:00 2001 From: songchengjiang Date: Tue, 17 Mar 2015 17:47:58 +0800 Subject: [PATCH 10/32] replace static_cast with dynamic_cast --- .../Particle3D/PU/CCPUDoAffectorEventHandler.cpp | 12 +++++++----- .../PU/CCPUDoEnableComponentEventHandler.cpp | 4 ++-- .../PU/CCPUDoPlacementParticleEventHandler.cpp | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/extensions/Particle3D/PU/CCPUDoAffectorEventHandler.cpp b/extensions/Particle3D/PU/CCPUDoAffectorEventHandler.cpp index 7ea0df9a52..1a71d568e1 100644 --- a/extensions/Particle3D/PU/CCPUDoAffectorEventHandler.cpp +++ b/extensions/Particle3D/PU/CCPUDoAffectorEventHandler.cpp @@ -51,11 +51,13 @@ void PUDoAffectorEventHandler::handle (PUParticleSystem3D* particleSystem, PUPar auto children = system->getChildren(); for(auto iter : children) { - technique = static_cast(iter); - affector = technique->getAffector(_affectorName); - if (affector) - { - break; + technique = dynamic_cast(iter); + if (technique){ + affector = technique->getAffector(_affectorName); + if (affector) + { + break; + } } } } diff --git a/extensions/Particle3D/PU/CCPUDoEnableComponentEventHandler.cpp b/extensions/Particle3D/PU/CCPUDoEnableComponentEventHandler.cpp index dd4d078130..ef1f3a9f37 100644 --- a/extensions/Particle3D/PU/CCPUDoEnableComponentEventHandler.cpp +++ b/extensions/Particle3D/PU/CCPUDoEnableComponentEventHandler.cpp @@ -138,8 +138,8 @@ void PUDoEnableComponentEventHandler::handle (PUParticleSystem3D* particleSystem if (system){ auto children = system->getChildren(); for (auto iter : children){ - PUParticleSystem3D *child = static_cast(iter); - if (child->getName() == _componentName){ + PUParticleSystem3D *child = dynamic_cast(iter); + if (child && child->getName() == _componentName){ child->setEnabled(_componentEnabled); break; } diff --git a/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp b/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp index c1b0d17cbc..14d86176c8 100644 --- a/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp +++ b/extensions/Particle3D/PU/CCPUDoPlacementParticleEventHandler.cpp @@ -80,7 +80,7 @@ void PUDoPlacementParticleEventHandler::handle (PUParticleSystem3D* particleSyst auto children = parentSystem->getChildren(); for(auto iter : children) { - PUParticleSystem3D *child = static_cast(iter); + PUParticleSystem3D *child = dynamic_cast(iter); if (child){ system = child; emitter = system->getEmitter(_forceEmitterName); From 5b55e873d0060c5cbdeef683f1b0653ae63901ab Mon Sep 17 00:00:00 2001 From: minggo Date: Tue, 17 Mar 2015 20:15:50 +0800 Subject: [PATCH 11/32] update document for CCAutoreleasePool.h --- cocos/base/CCAutoreleasePool.h | 59 +++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/cocos/base/CCAutoreleasePool.h b/cocos/base/CCAutoreleasePool.h index 1408469edf..7c73f70b35 100644 --- a/cocos/base/CCAutoreleasePool.h +++ b/cocos/base/CCAutoreleasePool.h @@ -40,7 +40,7 @@ class CC_DLL AutoreleasePool { public: /** - * @warn Don't create an auto release pool in heap, create it in stack. + * @warn Don't create an autorelease pool in heap, create it in stack. * @js NA * @lua NA */ @@ -48,6 +48,11 @@ public: /** * Create an autorelease pool with specific name. This name is useful for debugging. + * @warn Don't create an autorelease pool in heap, create it in stack. + * @js NA + * @lua NA + * + * @param name The name of created autorelease pool. */ AutoreleasePool(const std::string &name); @@ -58,13 +63,13 @@ public: ~AutoreleasePool(); /** - * Add a given object to this pool. + * Add a given object to this autorelease pool. * - * The same object may be added several times to the same pool; When the - * pool is destructed, the object's Ref::release() method will be called - * for each time it was added. + * The same object may be added several times to an autorelease pool. When the + * pool is destructed, the object's `Ref::release()` method will be called + * the same times as it was added. * - * @param object The object to add to the pool. + * @param object The object to be added into the autorelease pool. * @js NA * @lua NA */ @@ -73,8 +78,8 @@ public: /** * Clear the autorelease pool. * - * Ref::release() will be called for each time the managed object is - * added to the pool. + * It will invoke each element's `release()` function. + * * @js NA * @lua NA */ @@ -82,22 +87,34 @@ public: #if defined(COCOS2D_DEBUG) && (COCOS2D_DEBUG > 0) /** - * Whether the pool is doing `clear` operation. + * Whether the autorelease pool is doing `clear` operation. + * + * @return True if autorelase pool is clearning, false if not. + * + * @js NA + * @lua NA */ bool isClearing() const { return _isClearing; }; #endif /** - * Checks whether the pool contains the specified object. + * Checks whether the autorelease pool contains the specified object. + * + * @param object The object to be checked. + * @return True if the autorelease pool contains the object, false if not + * @js NA + * @lua NA */ bool contains(Ref* object) const; /** - * Dump the objects that are put into autorelease pool. It is used for debugging. + * Dump the objects that are put into the autorelease pool. It is used for debugging. * * The result will look like: * Object pointer address object id reference count * + * @js NA + * @lua NA */ void dump(); @@ -122,20 +139,16 @@ private: #endif }; +/** + * @cond + */ class CC_DLL PoolManager { public: - /** - * @js NA - * @lua NA - */ + CC_DEPRECATED_ATTRIBUTE static PoolManager* sharedPoolManager() { return getInstance(); } static PoolManager* getInstance(); - /** - * @js NA - * @lua NA - */ CC_DEPRECATED_ATTRIBUTE static void purgePoolManager() { destroyInstance(); } static void destroyInstance(); @@ -147,10 +160,7 @@ public: bool isObjectInPools(Ref* obj) const; - /** - * @js NA - * @lua NA - */ + friend class AutoreleasePool; private: @@ -164,6 +174,9 @@ private: std::vector _releasePoolStack; }; +/** + * @endcond + */ // end of base_nodes group /// @} From 36bf7c6d3913079f30bc4385f99defa33ca714d8 Mon Sep 17 00:00:00 2001 From: minggo Date: Tue, 17 Mar 2015 20:49:00 +0800 Subject: [PATCH 12/32] update document for CCAutoreleaseData.h --- cocos/base/CCData.h | 50 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 7 deletions(-) diff --git a/cocos/base/CCData.h b/cocos/base/CCData.h index 435e51eac0..d9bf9c0b10 100644 --- a/cocos/base/CCData.h +++ b/cocos/base/CCData.h @@ -33,28 +33,58 @@ NS_CC_BEGIN +/** + * @lua NA + */ class CC_DLL Data { public: + /** + * This parameter is defined for convenient reference if a null Data object is needed. + */ static const Data Null; + /** + * Constructor of Data. + */ Data(); + + /** + * Copy constructor of Data. + */ Data(const Data& other); + + /** + * Copy constructor of Data. + */ Data(Data&& other); + + /** + * Destructor of Data. + */ ~Data(); - // Assignment operator + /** + * Overroads of operator=. + */ Data& operator= (const Data& other); + + /** + * Overroads of operator=. + */ Data& operator= (Data&& other); /** - * @js NA - * @lua NA + * Gets internal bytes of Data. It will retrun the pointer directly used in Data, so don't delete it. + * + * @return Pointer of bytes used internal in Data. */ unsigned char* getBytes() const; + /** - * @js NA - * @lua NA + * Gets the size of the bytes. + * + * @return The size of bytes of Data. */ ssize_t getSize() const; @@ -74,10 +104,16 @@ public: */ void fastSet(unsigned char* bytes, const ssize_t size); - /** Clears data, free buffer and reset data size */ + /** + * Clears data, free buffer and reset data size. + */ void clear(); - /** Check whether the data is null. */ + /** + * Check whether the data is null. + * + * @return True if the the Data is null, false if not. + */ bool isNull() const; private: From 44c04153a6852647322d25ac5d728b6186ae504e Mon Sep 17 00:00:00 2001 From: minggo Date: Tue, 17 Mar 2015 20:54:47 +0800 Subject: [PATCH 13/32] update document for CCDataVisitor.h --- cocos/base/CCDataVisitor.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cocos/base/CCDataVisitor.h b/cocos/base/CCDataVisitor.h index ee25ff980f..42c51736d7 100644 --- a/cocos/base/CCDataVisitor.h +++ b/cocos/base/CCDataVisitor.h @@ -41,8 +41,7 @@ class __Dictionary; class __Set; /** - * @addtogroup data_structures - * @{ + * @cond */ /** @@ -106,8 +105,9 @@ private: std::string _result; }; -// end of data_structure group -/// @} +/** + * @endcond + */ NS_CC_END From 2aec39ad56cf81ce816dd9a2c490c1ab6f73c131 Mon Sep 17 00:00:00 2001 From: lyubomirv Date: Tue, 17 Mar 2015 15:14:02 +0200 Subject: [PATCH 14/32] Added Bulgarian language. --- cocos/platform/CCCommon.h | 3 ++- cocos/platform/android/CCApplication-android.cpp | 4 ++++ cocos/platform/ios/CCApplication-ios.mm | 3 +++ cocos/platform/linux/CCApplication-linux.cpp | 4 ++++ cocos/platform/mac/CCApplication-mac.mm | 3 +++ cocos/platform/win32/CCApplication-win32.cpp | 3 +++ cocos/platform/winrt/CCApplication.cpp | 4 ++++ 7 files changed, 23 insertions(+), 1 deletion(-) diff --git a/cocos/platform/CCCommon.h b/cocos/platform/CCCommon.h index a81fcb6280..b2707d2e8b 100644 --- a/cocos/platform/CCCommon.h +++ b/cocos/platform/CCCommon.h @@ -67,7 +67,8 @@ enum class LanguageType POLISH, TURKISH, UKRAINIAN, - ROMANIAN + ROMANIAN, + BULGARIAN }; // END of platform group diff --git a/cocos/platform/android/CCApplication-android.cpp b/cocos/platform/android/CCApplication-android.cpp index fb55ae001c..dacc0a33b1 100644 --- a/cocos/platform/android/CCApplication-android.cpp +++ b/cocos/platform/android/CCApplication-android.cpp @@ -188,6 +188,10 @@ LanguageType Application::getCurrentLanguage() { ret = LanguageType::ROMANIAN; } + else if (0 == strcmp("bg", pLanguageName)) + { + ret = LanguageType::BULGARIAN; + } return ret; } diff --git a/cocos/platform/ios/CCApplication-ios.mm b/cocos/platform/ios/CCApplication-ios.mm index 8563079159..0d515a575f 100644 --- a/cocos/platform/ios/CCApplication-ios.mm +++ b/cocos/platform/ios/CCApplication-ios.mm @@ -161,6 +161,9 @@ LanguageType Application::getCurrentLanguage() else if ([languageCode isEqualToString:@"ro"]){ ret = LanguageType::ROMANIAN; } + else if ([languageCode isEqualToString:@"bg"]){ + ret = LanguageType::BULGARIAN; + } return ret; } diff --git a/cocos/platform/linux/CCApplication-linux.cpp b/cocos/platform/linux/CCApplication-linux.cpp index 3302759c67..e88d064cf6 100644 --- a/cocos/platform/linux/CCApplication-linux.cpp +++ b/cocos/platform/linux/CCApplication-linux.cpp @@ -257,6 +257,10 @@ LanguageType Application::getCurrentLanguage() { ret = LanguageType::ROMANIAN; } + else if (0 == strcmp("bg", pLanguageName)) + { + ret = LanguageType::BULGARIAN; + } return ret; } diff --git a/cocos/platform/mac/CCApplication-mac.mm b/cocos/platform/mac/CCApplication-mac.mm index b9a7c64e9f..8593d58b7e 100644 --- a/cocos/platform/mac/CCApplication-mac.mm +++ b/cocos/platform/mac/CCApplication-mac.mm @@ -215,6 +215,9 @@ LanguageType Application::getCurrentLanguage() else if ([languageCode isEqualToString:@"ro"]){ ret = LanguageType::ROMANIAN; } + else if ([languageCode isEqualToString:@"bg"]){ + ret = LanguageType::BULGARIAN; + } return ret; } diff --git a/cocos/platform/win32/CCApplication-win32.cpp b/cocos/platform/win32/CCApplication-win32.cpp index 4d16d4f93f..6e2579b0b6 100644 --- a/cocos/platform/win32/CCApplication-win32.cpp +++ b/cocos/platform/win32/CCApplication-win32.cpp @@ -194,6 +194,9 @@ LanguageType Application::getCurrentLanguage() case LANG_ROMANIAN: ret = LanguageType::ROMANIAN; break; + case LANG_BULGARIAN: + ret = LanguageType::BULGARIAN; + break; } return ret; diff --git a/cocos/platform/winrt/CCApplication.cpp b/cocos/platform/winrt/CCApplication.cpp index d7d2410c95..8f1bf87280 100644 --- a/cocos/platform/winrt/CCApplication.cpp +++ b/cocos/platform/winrt/CCApplication.cpp @@ -205,6 +205,10 @@ LanguageType Application::getCurrentLanguage() { ret = LanguageType::ROMANIAN; } + else if (strncmp(code, "bg", 2) == 0) + { + ret = LanguageType::BULGARIAN; + } return ret; } From be2af445839ea38e42f0503cdf945e7ce59a29ba Mon Sep 17 00:00:00 2001 From: minggo Date: Tue, 17 Mar 2015 22:32:26 +0800 Subject: [PATCH 15/32] update document for CCDirector.h --- cocos/base/CCDirector.cpp | 2 - cocos/base/CCDirector.h | 267 +++++++++++++++++++++++--------------- 2 files changed, 160 insertions(+), 109 deletions(-) diff --git a/cocos/base/CCDirector.cpp b/cocos/base/CCDirector.cpp index 88260589ab..6a08b27ae8 100644 --- a/cocos/base/CCDirector.cpp +++ b/cocos/base/CCDirector.cpp @@ -248,8 +248,6 @@ void Director::setGLDefaultValues() CCASSERT(_openGLView, "opengl view should not be null"); setAlphaBlending(true); - // FIXME: Fix me, should enable/disable depth test according the depth format as cocos2d-iphone did - // [self setDepthTest: view_.depthFormat]; setDepthTest(false); setProjection(_projection); } diff --git a/cocos/base/CCDirector.h b/cocos/base/CCDirector.h index aa097876c6..932909f001 100644 --- a/cocos/base/CCDirector.h +++ b/cocos/base/CCDirector.h @@ -62,67 +62,73 @@ class Camera; class Console; /** -@brief Class that creates and handles the main Window and manages how -and when to execute the Scenes. - - The Director is also responsible for: - - initializing the OpenGL context - - setting the OpenGL pixel format (default on is RGB565) - - setting the OpenGL buffer depth (default one is 0-bit) - - setting the projection (default one is 3D) - - setting the orientation (default one is Portrait) - - Since the Director is a singleton, the standard way to use it is by calling: - _ Director::getInstance()->methodName(); - - The Director also sets the default OpenGL context: - - GL_TEXTURE_2D is enabled - - GL_VERTEX_ARRAY is enabled - - GL_COLOR_ARRAY is enabled - - GL_TEXTURE_COORD_ARRAY is enabled -*/ + * @brief Matrix stack type. + */ enum class MATRIX_STACK_TYPE { + /// Model view matrix stack MATRIX_STACK_MODELVIEW, + + /// projection matrix stack MATRIX_STACK_PROJECTION, + + /// texture matrix stack MATRIX_STACK_TEXTURE }; +/** + @brief Class that creates and handles the main Window and manages how + and when to execute the Scenes. + + The Director is also responsible for: + - initializing the OpenGL context + - setting the OpenGL buffer depth (default one is 0-bit) + - setting the projection (default one is 3D) + + Since the Director is a singleton, the standard way to use it is by calling: + _ Director::getInstance()->methodName(); + */ class CC_DLL Director : public Ref { public: + /** Director will trigger an event when projection type is changed. */ static const char *EVENT_PROJECTION_CHANGED; + /** Director will trigger an event after Schedule::update() is invoked. */ static const char* EVENT_AFTER_UPDATE; + /** Director will trigger an event after Scene::render() is invoked. */ static const char* EVENT_AFTER_VISIT; + /** Director will trigger an event after a scene is drawn, the data is sent to GPU. */ static const char* EVENT_AFTER_DRAW; - /** @typedef ccDirectorProjection - Possible OpenGL projections used by director + /** + * @brief Possible OpenGL projections used by director */ enum class Projection { - /// sets a 2D projection (orthogonal projection) + /// Sets a 2D projection (orthogonal projection). _2D, - /// sets a 3D projection with a fovy=60, znear=0.5f and zfar=1500. + /// Sets a 3D projection with a fovy=60, znear=0.5f and zfar=1500. _3D, - /// it calls "updateProjection" on the projection delegate. + /// It calls "updateProjection" on the projection delegate. CUSTOM, - /// Default projection is 3D projection + /// Default projection is 3D projection. DEFAULT = _3D, }; - /** returns a shared instance of the director */ + /** Returns a shared instance of the director. */ static Director* getInstance(); - /** @deprecated Use getInstance() instead */ + /** @deprecated Use getInstance() instead. */ CC_DEPRECATED_ATTRIBUTE static Director* sharedDirector() { return Director::getInstance(); } + /** * @js ctor */ - Director(void); + Director(); + /** * @js NA * @lua NA @@ -132,105 +138,128 @@ public: // attribute - /** Get current running Scene. Director can only run one Scene at a time */ + /** Gets current running Scene. Director can only run one Scene at a time. */ inline Scene* getRunningScene() { return _runningScene; } - /** Get the FPS value */ + /** Gets the FPS value. */ inline double getAnimationInterval() { return _animationInterval; } - /** Set the FPS value. */ + /** Sets the FPS value. FPS = 1/internal. */ virtual void setAnimationInterval(double interval) = 0; - /** Whether or not to display the FPS on the bottom-left corner */ + /** Whether or not to display the FPS on the bottom-left corner. */ inline bool isDisplayStats() { return _displayStats; } - /** Display the FPS on the bottom-left corner */ + /** Display the FPS on the bottom-left corner. */ inline void setDisplayStats(bool displayStats) { _displayStats = displayStats; } - /** seconds per frame */ + /** Get seconds per frame. */ inline float getSecondsPerFrame() { return _secondsPerFrame; } - /** Get the GLView, where everything is rendered - * @js NA - * @lua NA - */ + /** + * Get the GLView. + + * @js NA + * @lua NA + */ inline GLView* getOpenGLView() { return _openGLView; } + /** + * Sets the GLView. + * + * @lua NA + * @js NA + */ void setOpenGLView(GLView *openGLView); + /** Gets singleton of TextureCache. */ TextureCache* getTextureCache() const; + /** Whether or not `_nextDeltaTimeZero` is set to 0. */ inline bool isNextDeltaTimeZero() { return _nextDeltaTimeZero; } + /** + * Sets the detal time between current frame and next frame is 0. + * This value will be used in Schedule, and will affect all functions that are using frame detal time, such as Actions. + * This value will take effect only one time. + */ void setNextDeltaTimeZero(bool nextDeltaTimeZero); - /** Whether or not the Director is paused */ + /** Whether or not the Director is paused. */ inline bool isPaused() { return _paused; } /** How many frames were called since the director started */ inline unsigned int getTotalFrames() { return _totalFrames; } - /** Sets an OpenGL projection + /** Gets an OpenGL projection. @since v0.8.2 * @js NA * @lua NA */ inline Projection getProjection() { return _projection; } + /** Sets OpenGL projection. */ void setProjection(Projection projection); - /** Sets the glViewport*/ + /** Sets the glViewport.*/ void setViewport(); /** How many frames were called since the director started */ /** Whether or not the replaced scene will receive the cleanup message. - If the new scene is pushed, then the old scene won't receive the "cleanup" message. - If the new scene replaces the old one, the it will receive the "cleanup" message. - @since v0.99.0 + * If the new scene is pushed, then the old scene won't receive the "cleanup" message. + * If the new scene replaces the old one, the it will receive the "cleanup" message. + * @since v0.99.0 */ inline bool isSendCleanupToScene() { return _sendCleanupToScene; } /** This object will be visited after the main scene is visited. - This object MUST implement the "visit" selector. - Useful to hook a notification object, like Notifications (http://github.com/manucorporat/CCNotifications) - @since v0.99.5 + * This object MUST implement the "visit" function. + * Useful to hook a notification object, like Notifications (http://github.com/manucorporat/CCNotifications) + * @since v0.99.5 */ Node* getNotificationNode() const { return _notificationNode; } + /** + * Sets the notification node. + * @see Director::getNotificationNode() + */ void setNotificationNode(Node *node); // window size - /** returns the size of the OpenGL view in points. - */ + /** Returns the size of the OpenGL view in points. */ const Size& getWinSize() const; - /** returns the size of the OpenGL view in pixels. - */ + /** Returns the size of the OpenGL view in pixels. */ Size getWinSizeInPixels() const; - /** returns visible size of the OpenGL view in points. - * the value is equal to getWinSize if don't invoke - * GLView::setDesignResolutionSize() + /** + * Returns visible size of the OpenGL view in points. + * The value is equal to `Director::getWinSize()` if don't invoke `GLView::setDesignResolutionSize()`. */ Size getVisibleSize() const; - /** returns visible origin of the OpenGL view in points. - */ + /** Returns visible origin coordinate of the OpenGL view in points. */ Vec2 getVisibleOrigin() const; - /** converts a UIKit coordinate to an OpenGL coordinate - Useful to convert (multi) touch coordinates to the current layout (portrait or landscape) + /** + * Converts a screen coordinate to an OpenGL coordinate. + * Useful to convert (multi) touch coordinates to the current layout (portrait or landscape). */ Vec2 convertToGL(const Vec2& point); - /** converts an OpenGL coordinate to a UIKit coordinate - Useful to convert node points to window points for calls such as glScissor + /** + * Converts an OpenGL coordinate to a screen coordinate. + * Useful to convert node points to window points for calls such as glScissor. */ Vec2 convertToUI(const Vec2& point); - /// FIXME: missing description + /** + * Gets the distance between camera and near clipping frane. + * It is correct for default camera that near clipping frane is the same as screen. + */ float getZEye() const; // Scene Management - /** Enters the Director's main loop with the given Scene. + /** + * Enters the Director's main loop with the given Scene. * Call it to run only your FIRST scene. * Don't call it if there is already a running scene. * @@ -238,23 +267,26 @@ public: */ void runWithScene(Scene *scene); - /** Suspends the execution of the running scene, pushing it on the stack of suspended scenes. + /** + * Suspends the execution of the running scene, pushing it on the stack of suspended scenes. * The new scene will be executed. * Try to avoid big stacks of pushed scenes to reduce memory allocation. * ONLY call it if there is a running scene. */ void pushScene(Scene *scene); - /** Pops out a scene from the stack. + /** + * Pops out a scene from the stack. * This scene will replace the running one. * The running scene will be deleted. If there are no more scenes in the stack the execution is terminated. * ONLY call it if there is a running scene. */ void popScene(); - /** Pops out all scenes from the stack until the root scene in the queue. + /** + * Pops out all scenes from the stack until the root scene in the queue. * This scene will replace the running one. - * Internally it will call `popToSceneStackLevel(1)` + * Internally it will call `popToSceneStackLevel(1)`. */ void popToRootScene(); @@ -271,132 +303,153 @@ public: void replaceScene(Scene *scene); /** Ends the execution, releases the running scene. - It doesn't remove the OpenGL view from its parent. You have to do it manually. * @lua endToLua */ void end(); /** Pauses the running scene. - The running scene will be _drawed_ but all scheduled timers will be paused - While paused, the draw rate will be 4 FPS to reduce CPU consumption + * The running scene will be _drawed_ but all scheduled timers will be paused. + * While paused, the draw rate will be 4 FPS to reduce CPU consumption. */ void pause(); - /** Resumes the paused scene - The scheduled timers will be activated again. - The "delta time" will be 0 (as if the game wasn't paused) + /** Resumes the paused scene. + * The scheduled timers will be activated again. + * The "delta time" will be 0 (as if the game wasn't paused). */ void resume(); - /** Restart the director - */ + /** Restart the director. */ void restart(); /** Stops the animation. Nothing will be drawn. The main loop won't be triggered anymore. - If you don't want to pause your animation call [pause] instead. + * If you don't want to pause your animation call [pause] instead. */ virtual void stopAnimation() = 0; /** The main loop is triggered again. - Call this function only if [stopAnimation] was called earlier - @warning Don't call this function to start the main loop. To run the main loop call runWithScene + * Call this function only if [stopAnimation] was called earlier. + * @warning Don't call this function to start the main loop. To run the main loop call runWithScene. */ virtual void startAnimation() = 0; /** Draw the scene. - This method is called every frame. Don't call it manually. - */ + * This method is called every frame. Don't call it manually. + */ void drawScene(); // Memory Helper /** Removes all cocos2d cached data. - It will purge the TextureCache, SpriteFrameCache, LabelBMFont cache - @since v0.99.3 + * It will purge the TextureCache, SpriteFrameCache, LabelBMFont cache + * @since v0.99.3 */ void purgeCachedData(); - /** sets the default values based on the Configuration info */ + /** Sets the default values based on the Configuration info. */ void setDefaultValues(); // OpenGL Helper - /** sets the OpenGL default values */ + /** Sets the OpenGL default values. + * It will enable alpha blending, disable depth test. + */ void setGLDefaultValues(); - /** enables/disables OpenGL alpha blending */ + /** Enables/disables OpenGL alpha blending. */ void setAlphaBlending(bool on); - /** set clear values for the color buffers, value range of each element is [0.0, 1.0] */ + /** Sets clear values for the color buffers, value range of each element is [0.0, 1.0]. */ void setClearColor(const Color4F& clearColor); - /** enables/disables OpenGL depth test */ + /** Enables/disables OpenGL depth test. */ void setDepthTest(bool on); virtual void mainLoop() = 0; /** The size in pixels of the surface. It could be different than the screen size. - High-res devices might have a higher surface size than the screen size. - Only available when compiled using SDK >= 4.0. - @since v0.99.4 + * High-res devices might have a higher surface size than the screen size. + * Only available when compiled using SDK >= 4.0. + * @since v0.99.4 */ void setContentScaleFactor(float scaleFactor); + /** + * Gets content scale factor. + * @see Director::setContentScaleFactor() + */ float getContentScaleFactor() const { return _contentScaleFactor; } - /** Gets the Scheduler associated with this director - @since v2.0 + /** Gets the Scheduler associated with this director. + * @since v2.0 */ Scheduler* getScheduler() const { return _scheduler; } - /** Sets the Scheduler associated with this director - @since v2.0 + /** Sets the Scheduler associated with this director. + * @since v2.0 */ void setScheduler(Scheduler* scheduler); - /** Gets the ActionManager associated with this director - @since v2.0 + /** Gets the ActionManager associated with this director. + * @since v2.0 */ ActionManager* getActionManager() const { return _actionManager; } - /** Sets the ActionManager associated with this director - @since v2.0 + /** Sets the ActionManager associated with this director. + * @since v2.0 */ void setActionManager(ActionManager* actionManager); - /** Gets the EventDispatcher associated with this director - @since v3.0 + /** Gets the EventDispatcher associated with this director. + * @since v3.0 */ EventDispatcher* getEventDispatcher() const { return _eventDispatcher; } - /** Sets the EventDispatcher associated with this director - @since v3.0 + /** Sets the EventDispatcher associated with this director. + * @since v3.0 */ void setEventDispatcher(EventDispatcher* dispatcher); - /** Returns the Renderer - @since v3.0 + /** Returns the Renderer associated with this director. + * @since v3.0 */ Renderer* getRenderer() const { return _renderer; } - /** Returns the Console - @since v3.0 + /** Returns the Console associated with this director. + * @since v3.0 */ Console* getConsole() const { return _console; } - /* Gets delta time since last tick to main loop */ + /* Gets delta time since last tick to main loop. */ float getDeltaTime() const; /** - * get Frame Rate + * Gets Frame Rate. */ float getFrameRate() const { return _frameRate; } + /** Clones a specified type matrix and put it to the top of specified type of matrix stack. */ void pushMatrix(MATRIX_STACK_TYPE type); + /** Pops the top matrix of the specified type of matrix stack. */ void popMatrix(MATRIX_STACK_TYPE type); + /** Adds an identity matrix to the top of specified type of matrxi stack. */ void loadIdentityMatrix(MATRIX_STACK_TYPE type); + /** + * Adds a matrix to the top of specified type of matrix stack. + * + * @param type Matrix type. + * @param mat The matrix that to be added. + */ void loadMatrix(MATRIX_STACK_TYPE type, const Mat4& mat); + /** + * Multipies a matrix to the top of specified type of matrix stack. + * + * @param type Matrix type. + * @param mat The matrix that to be multipied. + */ void multiplyMatrix(MATRIX_STACK_TYPE type, const Mat4& mat); + /** Gets the top matrix of specified type of matrix stack. */ const Mat4& getMatrix(MATRIX_STACK_TYPE type); + /** Cleras all types of matrix stack, and add indentity matrix to these matrix stacks. */ void resetMatrixStack(); protected: From faf9d6b01c5c229f8a10cc68162b0c596b36aca4 Mon Sep 17 00:00:00 2001 From: pipu Date: Wed, 18 Mar 2015 10:28:12 +0800 Subject: [PATCH 16/32] Avoid crash during parse .csd file. --- cocos/editor-support/cocostudio/ActionTimeline/CSLoader.cpp | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/cocos/editor-support/cocostudio/ActionTimeline/CSLoader.cpp b/cocos/editor-support/cocostudio/ActionTimeline/CSLoader.cpp index e2c0e0fd0c..df59439683 100644 --- a/cocos/editor-support/cocostudio/ActionTimeline/CSLoader.cpp +++ b/cocos/editor-support/cocostudio/ActionTimeline/CSLoader.cpp @@ -1276,7 +1276,10 @@ Node* CSLoader::nodeWithFlatBuffersForSimulator(const flatbuffers::NodeTree *nod readername.append("Reader"); NodeReaderProtocol* reader = dynamic_cast(ObjectFactory::getInstance()->createObject(readername)); - node = reader->createNodeWithFlatBuffers(options->data()); + if (reader) + { + node = reader->createNodeWithFlatBuffers(options->data()); + } Widget* widget = dynamic_cast(node); if (widget) From 21d581a72c8f143645a6a3417d8a6dfe543aca6b Mon Sep 17 00:00:00 2001 From: yangxiao Date: Wed, 18 Mar 2015 11:41:43 +0800 Subject: [PATCH 17/32] set camera mask when member created --- cocos/2d/CCLabel.cpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cocos/2d/CCLabel.cpp b/cocos/2d/CCLabel.cpp index 3c60b2dce6..17c9af5206 100644 --- a/cocos/2d/CCLabel.cpp +++ b/cocos/2d/CCLabel.cpp @@ -932,6 +932,7 @@ void Label::createSpriteWithFontDefinition() texture->initWithString(_originalUTF8String.c_str(),_fontDefinition); _textSprite = Sprite::createWithTexture(texture); + _textSprite->setCameraMask(getCameraMask()); _textSprite->setAnchorPoint(Vec2::ANCHOR_BOTTOM_LEFT); this->setContentSize(_textSprite->getContentSize()); texture->release(); @@ -1073,6 +1074,7 @@ void Label::drawTextSprite(Renderer *renderer, uint32_t parentFlags) { _shadowNode->setBlendFunc(_blendFunc); } + _shadowNode->setCameraMask(getCameraMask()); _shadowNode->setAnchorPoint(Vec2::ANCHOR_BOTTOM_LEFT); _shadowNode->setColor(_shadowColor); _shadowNode->setOpacity(_shadowOpacity * _displayedOpacity); From 44af57459e20c2a4ab326041264101c10a6b286a Mon Sep 17 00:00:00 2001 From: yangxiao Date: Wed, 18 Mar 2015 11:58:36 +0800 Subject: [PATCH 18/32] add comment --- cocos/2d/CCLabel.cpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cocos/2d/CCLabel.cpp b/cocos/2d/CCLabel.cpp index 17c9af5206..27acb319fd 100644 --- a/cocos/2d/CCLabel.cpp +++ b/cocos/2d/CCLabel.cpp @@ -932,6 +932,7 @@ void Label::createSpriteWithFontDefinition() texture->initWithString(_originalUTF8String.c_str(),_fontDefinition); _textSprite = Sprite::createWithTexture(texture); + //set camera mask using label's camera mask, because _textSprite may be null when setting camera mask to label _textSprite->setCameraMask(getCameraMask()); _textSprite->setAnchorPoint(Vec2::ANCHOR_BOTTOM_LEFT); this->setContentSize(_textSprite->getContentSize()); @@ -1074,6 +1075,7 @@ void Label::drawTextSprite(Renderer *renderer, uint32_t parentFlags) { _shadowNode->setBlendFunc(_blendFunc); } + //set camera mask using label's mask. Because _shadowNode may be null when setting the label's camera mask _shadowNode->setCameraMask(getCameraMask()); _shadowNode->setAnchorPoint(Vec2::ANCHOR_BOTTOM_LEFT); _shadowNode->setColor(_shadowColor); From edf785cec3c8ae6619f3b312a46ba4ca35224a6b Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 13:52:52 +0800 Subject: [PATCH 19/32] [ci skip]update version --- cocos/cocos2d.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cocos/cocos2d.cpp b/cocos/cocos2d.cpp index 8f2e6483ff..6732f6baf6 100644 --- a/cocos/cocos2d.cpp +++ b/cocos/cocos2d.cpp @@ -31,7 +31,7 @@ NS_CC_BEGIN CC_DLL const char* cocos2dVersion() { - return "cocos2d-x 3.5rc0"; + return "cocos2d-x 3.5"; } NS_CC_END From 611ec0a4a53c7c5ebaaadabd93436a1654868ddc Mon Sep 17 00:00:00 2001 From: CocosRobot Date: Wed, 18 Mar 2015 05:55:07 +0000 Subject: [PATCH 20/32] [AUTO]: updating luabinding automatically --- cocos/scripting/lua-bindings/auto/api/ClippingNode.lua | 8 ++++++++ cocos/scripting/lua-bindings/auto/api/Label.lua | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/cocos/scripting/lua-bindings/auto/api/ClippingNode.lua b/cocos/scripting/lua-bindings/auto/api/ClippingNode.lua index 688394d901..9c8b443cf8 100644 --- a/cocos/scripting/lua-bindings/auto/api/ClippingNode.lua +++ b/cocos/scripting/lua-bindings/auto/api/ClippingNode.lua @@ -67,6 +67,14 @@ -- @param #cc.Node stencil -- @return ClippingNode#ClippingNode ret (return value: cc.ClippingNode) +-------------------------------- +-- +-- @function [parent=#ClippingNode] setCameraMask +-- @param self +-- @param #unsigned short mask +-- @param #bool applyChildren +-- @return ClippingNode#ClippingNode self (return value: cc.ClippingNode) + -------------------------------- -- -- @function [parent=#ClippingNode] visit diff --git a/cocos/scripting/lua-bindings/auto/api/Label.lua b/cocos/scripting/lua-bindings/auto/api/Label.lua index 4d389c0c55..dad4b8b300 100644 --- a/cocos/scripting/lua-bindings/auto/api/Label.lua +++ b/cocos/scripting/lua-bindings/auto/api/Label.lua @@ -478,4 +478,12 @@ -- @param #color3b_table parentColor -- @return Label#Label self (return value: cc.Label) +-------------------------------- +-- +-- @function [parent=#Label] setCameraMask +-- @param self +-- @param #unsigned short mask +-- @param #bool applyChildren +-- @return Label#Label self (return value: cc.Label) + return nil From eb2786f40d61700b00831bf9b1d8fbb3eda5b5b5 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 14:43:44 +0800 Subject: [PATCH 21/32] [ci skip]update comments CCVertexIndexData.h --- cocos/renderer/CCVertexIndexData.h | 49 +++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/cocos/renderer/CCVertexIndexData.h b/cocos/renderer/CCVertexIndexData.h index 78499c5cd3..b9cf06e749 100644 --- a/cocos/renderer/CCVertexIndexData.h +++ b/cocos/renderer/CCVertexIndexData.h @@ -31,7 +31,18 @@ NS_CC_BEGIN class VertexBuffer; +/** +VertexStreamAttribute is used to specify the vertex attribute for drawing, which is correspondent to +glVertexAttribPointer(GLuint indx, GLint size, GLenum type, GLboolean normalized, GLsizei stride, const GLvoid* ptr) + _semantic -> index + _size -> size + _type -> type + _normalize -> normalized + _offset is used to compute the start offset in a interleaved array, take a V3F_C4B_T2F array, + offset of vertex will be 0, offset of color would be 0 + sizeof(float) * 3 = 12, + offset of texture coord would be 12 + sizeof(char) * 4 = 16 +*/ struct CC_DLL VertexStreamAttribute { VertexStreamAttribute() @@ -56,30 +67,66 @@ struct CC_DLL VertexStreamAttribute int _size; }; +/** +VertexData is a class used for specify input streams for GPU rendering pipeline, +a VertexData will be composed by several streams, every stream will contain a VertexStreamAttribute +and the binding VertexBuffer. streams will be identified by semantic +*/ + class CC_DLL VertexData : public Ref { public: + /** + Create function, used to create a instance of VertexData + */ static VertexData* create(); + /*Get the number of streams in the VertexData*/ size_t getVertexStreamCount() const; + /** + Set a stream to VertexData,given that stream is identified by semantic, so if the semantic is not + specified before, it will add a stream, or it will override the old one + @param buffer The binding buffer of the stream + @param stream The binding vertex attribute, its member semantic will be used as the identifier. + */ bool setStream(VertexBuffer* buffer, const VertexStreamAttribute& stream); + /** + Remove the given streams + @param semantic The semantic of the stream + */ void removeStream(int semantic); + /** + Get the attribute of stream const version + @param semantic The semantic of the stream + */ const VertexStreamAttribute* getStreamAttribute(int semantic) const; + /** + Get the attribute of stream + @param semantic The semantic of the stream + */ VertexStreamAttribute* getStreamAttribute(int semantic); - + /** + Get the binded buffer of the stream + @param semantic The semantic of the stream + */ VertexBuffer* getStreamBuffer(int semantic) const; + /*Called for rendering, it will bind the state of vertex data to current rendering pipeline*/ void use(); protected: + /*Constructor*/ VertexData(); + /*Destructor*/ virtual ~VertexData(); protected: + /*Simple struct to bundle buffer and attribute*/ struct BufferAttribute { VertexBuffer* _buffer; VertexStreamAttribute _stream; }; + /*Streams in the VertexData*/ std::map _vertexStreams; }; From 0408fc0667ed24379199be07a0316ca440fbcd52 Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 18 Mar 2015 15:02:03 +0800 Subject: [PATCH 22/32] 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 a71fb9f946c6832c762e2e90980fdd2a6ed951f5 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 17:18:25 +0800 Subject: [PATCH 23/32] [ci skip]update comments CCVertexIndexBuffer.h --- cocos/renderer/CCVertexIndexBuffer.h | 83 +++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 7 deletions(-) diff --git a/cocos/renderer/CCVertexIndexBuffer.h b/cocos/renderer/CCVertexIndexBuffer.h index 4ee7070d87..08dfe9436a 100644 --- a/cocos/renderer/CCVertexIndexBuffer.h +++ b/cocos/renderer/CCVertexIndexBuffer.h @@ -33,45 +33,85 @@ NS_CC_BEGIN class EventListenerCustom; +/** +VertexBuffer is an abstraction of low level openGL Vertex Buffer Object. +It used to save an array of vertices +*/ class CC_DLL VertexBuffer : public Ref { public: + /** + Create an instance of VertexBuffer + @param sizePerVertex Size in bytes of one vertex + @param vertexNumber The number of vertex + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + */ static VertexBuffer* create(int sizePerVertex, int vertexNumber, GLenum usage = GL_STATIC_DRAW); - + /*Get the size in bytes of one vertex*/ int getSizePerVertex() const; + /*Get the number of vertices*/ int getVertexNumber() const; + /** + Update all or part of vertice data, if the range specified exceeds the vertex buffer, it will be clipped + @param verts The pointer of the vertex data + @param count The number of vertices to update + @param begin The first vertex to update + */ bool updateVertices(const void* verts, int count, int begin); + /*Get the size of the vertex array in bytes, equals getSizePerVertex() * getVertexNumber()*/ int getSize() const; - + /*Get the internal openGL handle*/ GLuint getVBO() const; protected: + /*Constructor*/ VertexBuffer(); + /*Destructor*/ virtual ~VertexBuffer(); - + /** + Init the storage of vertex buffer + @param sizePerVertex Size in bytes of one vertex + @param vertexNumber The number of vertex + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + */ bool init(int sizePerVertex, int vertexNumber, GLenum usage = GL_STATIC_DRAW); protected: //event listener for foreground void recreateVBO() const; EventListenerCustom* _recreateVBOEventListener; protected: + /*internal handle for openGL*/ mutable GLuint _vbo; + //size in bytes for one vertex int _sizePerVertex; + //number of vertices int _vertexNumber; //buffer used for shadow copy std::vector _shadowCopy; + //Hint for optimisation in GL GLenum _usage; protected: + //static member to indicate that use _shadowCopy or not static bool _enableShadowCopy; public: + /** + Static getter/setter for shadowCopy + */ static bool isShadowCopyEnabled() { return _enableShadowCopy; } static void enableShadowCopy(bool enabled) { _enableShadowCopy = enabled; } }; +/** +IndexBuffer is an abstraction of low level openGL Buffer Object. +It used to save an array of indices +*/ class CC_DLL IndexBuffer : public Ref { public: + /** + Enum for the type of index, short indices and int indices could be used + */ enum class IndexType { INDEX_TYPE_SHORT_16, @@ -79,26 +119,50 @@ public: }; public: + /** + Create an instance of IndexBuffer + @param type type of index + @param number The number of indices + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + */ static IndexBuffer* create(IndexType type, int number, GLenum usage = GL_STATIC_DRAW); - + //Getter for type of indices IndexType getType() const; + //Get the size in bytes for one index, will be 2 for INDEX_TYPE_SHORT_16 and 4 for INDEX_TYPE_UINT_32 int getSizePerIndex() const; + //Get the number of indices int getIndexNumber() const; + /** + Update all or part of indices data, if the range specified exceeds the vertex buffer, it will be clipped + @param indices The pointer of the index data + @param count The number of indices to update + @param begin The start index to update + */ bool updateIndices(const void* indices, int count, int begin); - + //Get the size in bytes of the array of indices int getSize() const; - + //Get the openGL handle for index buffer GLuint getVBO() const; protected: + //Constructor IndexBuffer(); + //Destructor virtual ~IndexBuffer(); - + /** + Init the storageof IndexBuffer + @param type type of index + @param number The number of indices + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + */ bool init(IndexType type, int number, GLenum usage = GL_STATIC_DRAW); protected: + //handle for openGL mutable GLuint _vbo; + //type for index IndexType _type; + //number of indices int _indexNumber; protected: @@ -107,10 +171,15 @@ protected: EventListenerCustom* _recreateVBOEventListener; //buffer used for shadow copy std::vector _shadowCopy; + //Hint for optimisation in GL GLenum _usage; protected: + //static member to indicate that use _shadowCopy or not static bool _enableShadowCopy; public: + /** + Static getter/setter for shadowCopy + */ static bool isShadowCopyEnabled() { return _enableShadowCopy; } static void enableShadowCopy(bool enabled) { _enableShadowCopy = enabled; } }; From fb1d9899c79adc107024821b2fd12830178328c8 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 17:40:10 +0800 Subject: [PATCH 24/32] [ci skip]adjust comments CCVertexIndexBuffer.h and CCVertexIndexData.h --- cocos/renderer/CCVertexIndexBuffer.h | 168 ++++++++++++++++++--------- cocos/renderer/CCVertexIndexData.h | 52 +++++---- 2 files changed, 144 insertions(+), 76 deletions(-) diff --git a/cocos/renderer/CCVertexIndexBuffer.h b/cocos/renderer/CCVertexIndexBuffer.h index 08dfe9436a..74fde4ddf7 100644 --- a/cocos/renderer/CCVertexIndexBuffer.h +++ b/cocos/renderer/CCVertexIndexBuffer.h @@ -35,68 +35,93 @@ class EventListenerCustom; /** VertexBuffer is an abstraction of low level openGL Vertex Buffer Object. -It used to save an array of vertices +It is used to save an array of vertices. */ class CC_DLL VertexBuffer : public Ref { public: /** - Create an instance of VertexBuffer - @param sizePerVertex Size in bytes of one vertex - @param vertexNumber The number of vertex - @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + Create an instance of VertexBuffer. + @param sizePerVertex Size in bytes of one vertex. + @param vertexNumber The number of vertex. + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it. */ static VertexBuffer* create(int sizePerVertex, int vertexNumber, GLenum usage = GL_STATIC_DRAW); - /*Get the size in bytes of one vertex*/ + /**Get the size in bytes of one vertex.*/ int getSizePerVertex() const; - /*Get the number of vertices*/ + /**Get the number of vertices.*/ int getVertexNumber() const; /** - Update all or part of vertice data, if the range specified exceeds the vertex buffer, it will be clipped - @param verts The pointer of the vertex data - @param count The number of vertices to update - @param begin The first vertex to update + Update all or part of vertice data, if the range specified exceeds the vertex buffer, it will be clipped. + @param verts The pointer of the vertex data. + @param count The number of vertices to update. + @param begin The first vertex to update. */ bool updateVertices(const void* verts, int count, int begin); - /*Get the size of the vertex array in bytes, equals getSizePerVertex() * getVertexNumber()*/ + /** + Get the size of the vertex array in bytes, equals getSizePerVertex() * getVertexNumber(). + */ int getSize() const; - /*Get the internal openGL handle*/ + /** + Get the internal openGL handle. + */ GLuint getVBO() const; protected: - /*Constructor*/ + /** + Constructor. + */ VertexBuffer(); - /*Destructor*/ + /** + Destructor. + */ virtual ~VertexBuffer(); /** - Init the storage of vertex buffer - @param sizePerVertex Size in bytes of one vertex - @param vertexNumber The number of vertex - @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + Init the storage of vertex buffer. + @param sizePerVertex Size in bytes of one vertex. + @param vertexNumber The number of vertex. + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it. */ bool init(int sizePerVertex, int vertexNumber, GLenum usage = GL_STATIC_DRAW); protected: - //event listener for foreground + /** + Event handler for foreground. + */ void recreateVBO() const; + /** + Event listener for foreground. + */ EventListenerCustom* _recreateVBOEventListener; protected: - /*internal handle for openGL*/ + /** + Internal handle for openGL. + */ mutable GLuint _vbo; - //size in bytes for one vertex + /** + Size in bytes for one vertex. + */ int _sizePerVertex; - //number of vertices + /** + Number of vertices. + */ int _vertexNumber; - //buffer used for shadow copy + /** + Buffer used for shadow copy. + */ std::vector _shadowCopy; - //Hint for optimisation in GL + /** + Hint for optimisation in GL. + */ GLenum _usage; protected: - //static member to indicate that use _shadowCopy or not + /** + Static member to indicate that use _shadowCopy or not. + */ static bool _enableShadowCopy; public: /** - Static getter/setter for shadowCopy + Static getter/setter for shadowCopy. */ static bool isShadowCopyEnabled() { return _enableShadowCopy; } static void enableShadowCopy(bool enabled) { _enableShadowCopy = enabled; } @@ -104,13 +129,13 @@ public: /** IndexBuffer is an abstraction of low level openGL Buffer Object. -It used to save an array of indices +It used to save an array of indices. */ class CC_DLL IndexBuffer : public Ref { public: /** - Enum for the type of index, short indices and int indices could be used + Enum for the type of index, short indices and int indices could be used. */ enum class IndexType { @@ -120,65 +145,96 @@ public: public: /** - Create an instance of IndexBuffer - @param type type of index - @param number The number of indices - @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + Create an instance of IndexBuffer. + @param type type of index. + @param number The number of indices. + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it. */ static IndexBuffer* create(IndexType type, int number, GLenum usage = GL_STATIC_DRAW); - //Getter for type of indices + /** + Getter for type of indices. + */ IndexType getType() const; - //Get the size in bytes for one index, will be 2 for INDEX_TYPE_SHORT_16 and 4 for INDEX_TYPE_UINT_32 + /** + Get the size in bytes for one index, will be 2 for INDEX_TYPE_SHORT_16 and 4 for INDEX_TYPE_UINT_32. + */ int getSizePerIndex() const; - //Get the number of indices + /** + Get the number of indices. + */ int getIndexNumber() const; /** - Update all or part of indices data, if the range specified exceeds the vertex buffer, it will be clipped - @param indices The pointer of the index data - @param count The number of indices to update - @param begin The start index to update + Update all or part of indices data, if the range specified exceeds the vertex buffer, it will be clipped. + @param indices The pointer of the index data. + @param count The number of indices to update. + @param begin The start index to update. */ bool updateIndices(const void* indices, int count, int begin); - //Get the size in bytes of the array of indices + /** + Get the size in bytes of the array of indices. + */ int getSize() const; - //Get the openGL handle for index buffer + /** + Get the openGL handle for index buffer. + */ GLuint getVBO() const; protected: - //Constructor + /** + Constructor. + */ IndexBuffer(); - //Destructor + /** + Destructor. + */ virtual ~IndexBuffer(); /** - Init the storageof IndexBuffer - @param type type of index - @param number The number of indices - @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it + Init the storageof IndexBuffer. + @param type type of index. + @param number The number of indices. + @param usage A hint to indicate whether the vertexBuffer are updated frequently or not to let GL optimise it. */ bool init(IndexType type, int number, GLenum usage = GL_STATIC_DRAW); protected: - //handle for openGL + /** + Handle for openGL. + */ mutable GLuint _vbo; - //type for index + /** + Type for index. + */ IndexType _type; - //number of indices + /** + Number of indices. + */ int _indexNumber; protected: - //event listener for foreground + /** + Event handler for foreground. + */ void recreateVBO() const; + /** + Event listener for foreground. + */ EventListenerCustom* _recreateVBOEventListener; - //buffer used for shadow copy + /** + Buffer used for shadow copy. + */ std::vector _shadowCopy; - //Hint for optimisation in GL + /** + Hint for optimisation in GL. + */ GLenum _usage; protected: - //static member to indicate that use _shadowCopy or not + /** + Static member to indicate that use _shadowCopy or not. + */ static bool _enableShadowCopy; public: /** - Static getter/setter for shadowCopy + Static getter/setter for shadowCopy. */ static bool isShadowCopyEnabled() { return _enableShadowCopy; } static void enableShadowCopy(bool enabled) { _enableShadowCopy = enabled; } diff --git a/cocos/renderer/CCVertexIndexData.h b/cocos/renderer/CCVertexIndexData.h index b9cf06e749..d336db4e35 100644 --- a/cocos/renderer/CCVertexIndexData.h +++ b/cocos/renderer/CCVertexIndexData.h @@ -33,7 +33,7 @@ NS_CC_BEGIN class VertexBuffer; /** VertexStreamAttribute is used to specify the vertex attribute for drawing, which is correspondent to -glVertexAttribPointer(GLuint indx, GLint size, GLenum type, GLboolean normalized, GLsizei stride, const GLvoid* ptr) +glVertexAttribPointer(GLuint indx, GLint size, GLenum type, GLboolean normalized, GLsizei stride, const GLvoid* ptr). _semantic -> index _size -> size @@ -41,7 +41,7 @@ glVertexAttribPointer(GLuint indx, GLint size, GLenum type, GLboolean normalized _normalize -> normalized _offset is used to compute the start offset in a interleaved array, take a V3F_C4B_T2F array, offset of vertex will be 0, offset of color would be 0 + sizeof(float) * 3 = 12, - offset of texture coord would be 12 + sizeof(char) * 4 = 16 + offset of texture coord would be 12 + sizeof(char) * 4 = 16. */ struct CC_DLL VertexStreamAttribute { @@ -70,63 +70,75 @@ struct CC_DLL VertexStreamAttribute /** VertexData is a class used for specify input streams for GPU rendering pipeline, a VertexData will be composed by several streams, every stream will contain a VertexStreamAttribute -and the binding VertexBuffer. streams will be identified by semantic +and the binding VertexBuffer. Streams will be identified by semantic. */ class CC_DLL VertexData : public Ref { public: /** - Create function, used to create a instance of VertexData + Create function, used to create a instance of VertexData. */ static VertexData* create(); - /*Get the number of streams in the VertexData*/ + /** + Get the number of streams in the VertexData. + */ size_t getVertexStreamCount() const; /** Set a stream to VertexData,given that stream is identified by semantic, so if the semantic is not - specified before, it will add a stream, or it will override the old one - @param buffer The binding buffer of the stream + specified before, it will add a stream, or it will override the old one. + @param buffer The binding buffer of the stream. @param stream The binding vertex attribute, its member semantic will be used as the identifier. */ bool setStream(VertexBuffer* buffer, const VertexStreamAttribute& stream); /** - Remove the given streams - @param semantic The semantic of the stream + Remove the given streams. + @param semantic The semantic of the stream. */ void removeStream(int semantic); /** - Get the attribute of stream const version - @param semantic The semantic of the stream + Get the attribute of stream, const version. + @param semantic The semantic of the stream. */ const VertexStreamAttribute* getStreamAttribute(int semantic) const; /** - Get the attribute of stream - @param semantic The semantic of the stream + Get the attribute of stream. + @param semantic The semantic of the stream. */ VertexStreamAttribute* getStreamAttribute(int semantic); /** - Get the binded buffer of the stream - @param semantic The semantic of the stream + Get the binded buffer of the stream. + @param semantic The semantic of the stream. */ VertexBuffer* getStreamBuffer(int semantic) const; - /*Called for rendering, it will bind the state of vertex data to current rendering pipeline*/ + /** + Called for rendering, it will bind the state of vertex data to current rendering pipeline. + */ void use(); protected: - /*Constructor*/ + /** + Constructor. + */ VertexData(); - /*Destructor*/ + /** + Destructor. + */ virtual ~VertexData(); protected: - /*Simple struct to bundle buffer and attribute*/ + /** + Simple struct to bundle buffer and attribute. + */ struct BufferAttribute { VertexBuffer* _buffer; VertexStreamAttribute _stream; }; - /*Streams in the VertexData*/ + /** + Streams in the VertexData. + */ std::map _vertexStreams; }; From b55916c283ac8b3d905afee8ec1460b190465cac Mon Sep 17 00:00:00 2001 From: zhangbin Date: Wed, 18 Mar 2015 18:15:34 +0800 Subject: [PATCH 25/32] Update comments of some header files. --- cocos/2d/CCActionEase.h | 486 +++++++++++++++++++++---------- cocos/2d/CCActionGrid.h | 173 ++++++++--- cocos/2d/CCActionGrid3D.h | 382 +++++++++++++++++++----- cocos/2d/CCActionPageTurn3D.h | 17 +- cocos/2d/CCActionProgressTimer.h | 39 ++- cocos/2d/CCActionTween.h | 34 ++- 6 files changed, 833 insertions(+), 298 deletions(-) diff --git a/cocos/2d/CCActionEase.h b/cocos/2d/CCActionEase.h index 327fbac4d8..11b1b2a93f 100644 --- a/cocos/2d/CCActionEase.h +++ b/cocos/2d/CCActionEase.h @@ -37,13 +37,20 @@ NS_CC_BEGIN */ /** - @brief Base class for Easing actions + @class ActionEase + @brief Base class for Easing actions. + @detail Ease actions are created from other interval actions. + The ease action will change the timeline of the inner action. @ingroup Actions */ class CC_DLL ActionEase : public ActionInterval { public: + /** + @brief Get the pointer of the inner action. + @return The pointer of the inner action. + */ virtual ActionInterval* getInnerAction(); // @@ -63,15 +70,15 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop() override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: ActionEase() {} virtual ~ActionEase(); - /** initializes the action */ + /** + @brief Initializes the action. + @return Return true when the initialization success, otherwise return false. + */ bool initWithAction(ActionInterval *action); protected: @@ -82,15 +89,23 @@ private: }; /** - @brief Base class for Easing actions with rate parameters + @class EaseRateAction + @brief Base class for Easing actions with rate parameters. + @detail Ease the inner action with specified rate. @ingroup Actions */ class CC_DLL EaseRateAction : public ActionEase { public: - /** set rate value for the actions */ + /** + @brief Set the rate value for the ease rate action. + @param rate The value will be set. + */ inline void setRate(float rate) { _rate = rate; } - /** get rate value for the actions */ + /** + @brief Get the rate value of the ease rate action. + @return Return the rate value of the ease rate action. + */ inline float getRate() const { return _rate; } // @@ -110,7 +125,12 @@ public: CC_CONSTRUCTOR_ACCESS: EaseRateAction() {} virtual ~EaseRateAction(); - /** Initializes the action with the inner action and the rate parameter */ + /** + @brief Initializes the action with the inner action and the rate parameter. + @param pAction The pointer of the inner action. + @param fRate The value of the rate parameter. + @return Return true when the initialization success, otherwise return false. + */ bool initWithAction(ActionInterval *pAction, float fRate); protected: @@ -121,19 +141,24 @@ private: }; /** - @brief EaseIn action with a rate + @class EaseIn + @brief EaseIn action with a rate. + @detail The timeline of inner action will be changed by: + \f$time^rate\f$ @ingroup Actions */ class CC_DLL EaseIn : public EaseRateAction { public: - /** Creates the action with the inner action and the rate parameter */ + /** + @brief Create the action with the inner action and the rate parameter. + @param action The pointer of the inner action. + @param rate The value of the rate parameter. + @return A pointer of EaseIn action. If creation failed, return nil. + */ static EaseIn* create(ActionInterval* action, float rate); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseIn* clone() const override; virtual EaseIn* reverse() const override; @@ -147,19 +172,24 @@ private: }; /** - @brief EaseOut action with a rate + @class EaseOut + @brief EaseOut action with a rate. + @detail The timeline of inner action will be changed by: + \f$time^(1/rate)\f$ @ingroup Actions */ class CC_DLL EaseOut : public EaseRateAction { public: - /** Creates the action with the inner action and the rate parameter */ + /** + @brief Create the action with the inner action and the rate parameter. + @param action The pointer of the inner action. + @param rate The value of the rate parameter. + @return A pointer of EaseOut action. If creation failed, return nil. + */ static EaseOut* create(ActionInterval* action, float rate); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseOut* clone() const override; virtual EaseOut* reverse() const override; @@ -173,19 +203,26 @@ 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$ + Else, the timeline of inner action will be changed by: + \f$1.0-0.5*{ 2-time }^{ rate }\f$ @ingroup Actions */ class CC_DLL EaseInOut : public EaseRateAction { public: - /** Creates the action with the inner action and the rate parameter */ + /** + @brief Create the action with the inner action and the rate parameter. + @param action The pointer of the inner action. + @param rate The value of the rate parameter. + @return A pointer of EaseInOut action. If creation failed, return nil. + */ static EaseInOut* create(ActionInterval* action, float rate); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseInOut* clone() const override; virtual EaseInOut* reverse() const override; @@ -199,19 +236,23 @@ private: }; /** - @brief Ease Exponential In + @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$ @ingroup Actions */ class CC_DLL EaseExponentialIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseExponentialIn action. If creation failed, return nil. + */ static EaseExponentialIn* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseExponentialIn* clone() const override; virtual ActionEase* reverse() const override; @@ -225,19 +266,23 @@ private: }; /** + @class EaseExponentialOut @brief Ease Exponential Out + @detail The timeline of inner action will be changed by: + \f$1-{ 2 }^{ -10*(time-1) }\f$ @ingroup Actions */ class CC_DLL EaseExponentialOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseExponentialOut action. If creation failed, return nil. + */ static EaseExponentialOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseExponentialOut* clone() const override; virtual ActionEase* reverse() const override; @@ -251,19 +296,25 @@ 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$ + else, the timeline of inner action will be changed by: + \f$0.5*(2-{ 2 }^{ -10*(time-1) })\f$ @ingroup Actions */ class CC_DLL EaseExponentialInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseExponentialInOut action. If creation failed, return nil. + */ static EaseExponentialInOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseExponentialInOut* clone() const override; virtual EaseExponentialInOut* reverse() const override; @@ -277,19 +328,23 @@ 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$ @ingroup Actions */ class CC_DLL EaseSineIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseSineIn action. If creation failed, return nil. + */ static EaseSineIn* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseSineIn* clone() const override; virtual ActionEase* reverse() const override; @@ -303,19 +358,23 @@ private: }; /** + @class EaseSineOut @brief Ease Sine Out + @detail The timeline of inner action will be changed by: + \f$sin(time*\frac { \pi }{ 2 } )\f$ @ingroup Actions */ class CC_DLL EaseSineOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseSineOut action. If creation failed, return nil. + */ static EaseSineOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseSineOut* clone() const override; virtual ActionEase* reverse() const override; @@ -329,19 +388,23 @@ 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$ @ingroup Actions */ class CC_DLL EaseSineInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseSineInOut action. If creation failed, return nil. + */ static EaseSineInOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseSineInOut* clone() const override; virtual EaseSineInOut* reverse() const override; @@ -355,6 +418,7 @@ private: }; /** + @class EaseElastic @brief Ease Elastic abstract class @since v0.8.2 @ingroup Actions @@ -363,9 +427,15 @@ class CC_DLL EaseElastic : public ActionEase { public: - /** get period of the wave in radians. default is 0.3 */ + /** + @brief Get period of the wave in radians. Default value is 0.3. + @return Return the period of the wave in radians. + */ inline float getPeriod() const { return _period; } - /** set period of the wave in radians. */ + /** + @brief Set period of the wave in radians. + @param fPeriod The value will be set. + */ inline void setPeriod(float fPeriod) { _period = fPeriod; } // @@ -386,7 +456,12 @@ public: CC_CONSTRUCTOR_ACCESS: EaseElastic() {} virtual ~EaseElastic() {} - /** Initializes the action with the inner action and the period in radians (default is 0.3) */ + /** + @brief Initializes the action with the inner action and the period in radians. + @param action The pointer of the inner action. + @param period Period of the wave in radians. Default is 0.3. + @return Return true when the initialization success, otherwise return false. + */ bool initWithAction(ActionInterval *action, float period = 0.3f); protected: @@ -398,22 +473,36 @@ private: }; /** + @class EaseElasticIn @brief Ease Elastic In action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this 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$ + + @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 @ingroup Actions */ class CC_DLL EaseElasticIn : public EaseElastic { public: - /** Creates the action with the inner action and the period in radians (default is 0.3) */ + /** + @brief Create the EaseElasticIn action with the inner action and the period in radians. + @param action The pointer of the inner action. + @param period Period of the wave in radians. + @return A pointer of EaseElasticIn action. If creation failed, return nil. + */ static EaseElasticIn* create(ActionInterval *action, float period); + + /** + @brief Create the EaseElasticIn action with the inner action and period value is 0.3. + @param action The pointer of the inner action. + @return A pointer of EaseElasticIn action. If creation failed, return nil. + */ static EaseElasticIn* create(ActionInterval *action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseElasticIn* clone() const override; virtual EaseElastic* reverse() const override; @@ -427,22 +516,35 @@ private: }; /** + @class EaseElasticOut @brief Ease Elastic Out action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this 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$ + @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 @ingroup Actions */ class CC_DLL EaseElasticOut : public EaseElastic { public: - /** Creates the action with the inner action and the period in radians (default is 0.3) */ + /** + @brief Create the EaseElasticOut action with the inner action and the period in radians. + @param action The pointer of the inner action. + @param period Period of the wave in radians. + @return A pointer of EaseElasticOut action. If creation failed, return nil. + */ static EaseElasticOut* create(ActionInterval *action, float period); + + /** + @brief Create the EaseElasticOut action with the inner action and period value is 0.3. + @param action The pointer of the inner action. + @return A pointer of EaseElasticOut action. If creation failed, return nil. + */ static EaseElasticOut* create(ActionInterval *action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseElasticOut* clone() const override; virtual EaseElastic* reverse() const override; @@ -456,22 +558,32 @@ private: }; /** + @class EaseElasticInOut @brief Ease Elastic InOut action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseElasticInOut : public EaseElastic { public: - /** Creates the action with the inner action and the period in radians (default is 0.3) */ + /** + @brief Create the EaseElasticInOut action with the inner action and the period in radians. + @param action The pointer of the inner action. + @param period Period of the wave in radians. + @return A pointer of EaseElasticInOut action. If creation failed, return nil. + */ static EaseElasticInOut* create(ActionInterval *action, float period); + + /** + @brief Create the EaseElasticInOut action with the inner action and period value is 0.3. + @param action The pointer of the inner action. + @return A pointer of EaseElasticInOut action. If creation failed, return nil. + */ static EaseElasticInOut* create(ActionInterval *action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseElasticInOut* clone() const override; virtual EaseElasticInOut* reverse() const override; @@ -485,6 +597,7 @@ private: }; /** + @class EaseBounce @brief EaseBounce abstract class. @since v0.8.2 @ingroup Actions @@ -515,21 +628,24 @@ private: }; /** + @class EaseBounceIn @brief EaseBounceIn action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseBounceIn : public EaseBounce { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBounceIn action. If creation failed, return nil. + */ static EaseBounceIn* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBounceIn* clone() const override; virtual EaseBounce* reverse() const override; @@ -543,21 +659,24 @@ private: }; /** + @class EaseBounceOut @brief EaseBounceOut action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseBounceOut : public EaseBounce { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBounceOut action. If creation failed, return nil. + */ static EaseBounceOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBounceOut* clone() const override; virtual EaseBounce* reverse() const override; @@ -571,21 +690,24 @@ private: }; /** + @class EaseBounceInOut @brief EaseBounceInOut action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseBounceInOut : public EaseBounce { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBounceInOut action. If creation failed, return nil. + */ static EaseBounceInOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBounceInOut* clone() const override; virtual EaseBounceInOut* reverse() const override; @@ -599,21 +721,24 @@ private: }; /** + @class EaseBackIn @brief EaseBackIn action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseBackIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBackIn action. If creation failed, return nil. + */ static EaseBackIn* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBackIn* clone() const override; virtual ActionEase* reverse() const override; @@ -627,21 +752,24 @@ private: }; /** + @class EaseBackOut @brief EaseBackOut action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseBackOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBackOut action. If creation failed, return nil. + */ static EaseBackOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBackOut* clone() const override; virtual ActionEase* reverse() const override; @@ -655,21 +783,24 @@ private: }; /** + @class EaseBackInOut @brief EaseBackInOut action. - @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. + @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 @ingroup Actions */ class CC_DLL EaseBackInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBackInOut action. If creation failed, return nil. + */ static EaseBackInOut* create(ActionInterval* action); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBackInOut* clone() const override; virtual EaseBackInOut* reverse() const override; @@ -684,22 +815,27 @@ private: /** +@class EaseBezierAction @brief Ease Bezier @ingroup Actions */ class CC_DLL EaseBezierAction : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseBezierAction action. If creation failed, return nil. + */ static EaseBezierAction* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseBezierAction* clone() const override; virtual EaseBezierAction* reverse() const override; + /** + @brief Set the bezier parameters. + */ virtual void setBezierParamer( float p0, float p1, float p2, float p3); CC_CONSTRUCTOR_ACCESS: @@ -717,18 +853,20 @@ private: }; /** +@class EaseQuadraticActionIn @brief Ease Quadratic In @ingroup Actions */ class CC_DLL EaseQuadraticActionIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuadraticActionIn action. If creation failed, return nil. + */ static EaseQuadraticActionIn* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuadraticActionIn* clone() const override; virtual EaseQuadraticActionIn* reverse() const override; @@ -743,18 +881,20 @@ private: }; /** +@class EaseQuadraticActionOut @brief Ease Quadratic Out @ingroup Actions */ class CC_DLL EaseQuadraticActionOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuadraticActionOut action. If creation failed, return nil. + */ static EaseQuadraticActionOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuadraticActionOut* clone() const override; virtual EaseQuadraticActionOut* reverse() const override; @@ -769,18 +909,20 @@ private: }; /** +@class EaseQuadraticActionInOut @brief Ease Quadratic InOut @ingroup Actions */ class CC_DLL EaseQuadraticActionInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuadraticActionInOut action. If creation failed, return nil. + */ static EaseQuadraticActionInOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuadraticActionInOut* clone() const override; virtual EaseQuadraticActionInOut* reverse() const override; @@ -794,18 +936,20 @@ private: }; /** +@class EaseQuarticActionIn @brief Ease Quartic In @ingroup Actions */ class CC_DLL EaseQuarticActionIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuarticActionIn action. If creation failed, return nil. + */ static EaseQuarticActionIn* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuarticActionIn* clone() const override; virtual EaseQuarticActionIn* reverse() const override; @@ -819,18 +963,20 @@ private: }; /** +@class EaseQuarticActionOut @brief Ease Quartic Out @ingroup Actions */ class CC_DLL EaseQuarticActionOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuarticActionOut action. If creation failed, return nil. + */ static EaseQuarticActionOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuarticActionOut* clone() const override; virtual EaseQuarticActionOut* reverse() const override; @@ -844,18 +990,20 @@ private: }; /** +@class EaseQuarticActionInOut @brief Ease Quartic InOut @ingroup Actions */ class CC_DLL EaseQuarticActionInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuarticActionInOut action. If creation failed, return nil. + */ static EaseQuarticActionInOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuarticActionInOut* clone() const override; virtual EaseQuarticActionInOut* reverse() const override; @@ -870,18 +1018,20 @@ private: /** +@class EaseQuinticActionIn @brief Ease Quintic In @ingroup Actions */ class CC_DLL EaseQuinticActionIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuinticActionIn action. If creation failed, return nil. + */ static EaseQuinticActionIn* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuinticActionIn* clone() const override; virtual EaseQuinticActionIn* reverse() const override; @@ -895,18 +1045,20 @@ private: }; /** +@class EaseQuinticActionOut @brief Ease Quintic Out @ingroup Actions */ class CC_DLL EaseQuinticActionOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuinticActionOut action. If creation failed, return nil. + */ static EaseQuinticActionOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuinticActionOut* clone() const override; virtual EaseQuinticActionOut* reverse() const override; @@ -920,18 +1072,20 @@ private: }; /** +@class EaseQuinticActionInOut @brief Ease Quintic InOut @ingroup Actions */ class CC_DLL EaseQuinticActionInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseQuinticActionInOut action. If creation failed, return nil. + */ static EaseQuinticActionInOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseQuinticActionInOut* clone() const override; virtual EaseQuinticActionInOut* reverse() const override; @@ -945,18 +1099,20 @@ private: }; /** +@class EaseCircleActionIn @brief Ease Circle In @ingroup Actions */ class CC_DLL EaseCircleActionIn : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseCircleActionIn action. If creation failed, return nil. + */ static EaseCircleActionIn* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseCircleActionIn* clone() const override; virtual EaseCircleActionIn* reverse() const override; @@ -970,18 +1126,20 @@ private: }; /** +@class EaseCircleActionOut @brief Ease Circle Out @ingroup Actions */ class CC_DLL EaseCircleActionOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseCircleActionOut action. If creation failed, return nil. + */ static EaseCircleActionOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseCircleActionOut* clone() const override; virtual EaseCircleActionOut* reverse() const override; @@ -995,18 +1153,20 @@ private: }; /** +@class EaseCircleActionInOut @brief Ease Circle InOut @ingroup Actions */ class CC_DLL EaseCircleActionInOut:public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseCircleActionInOut action. If creation failed, return nil. + */ static EaseCircleActionInOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseCircleActionInOut* clone() const override; virtual EaseCircleActionInOut* reverse() const override; @@ -1020,18 +1180,20 @@ private: }; /** +@class EaseCubicActionIn @brief Ease Cubic In @ingroup Actions */ class CC_DLL EaseCubicActionIn:public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseCubicActionIn action. If creation failed, return nil. + */ static EaseCubicActionIn* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseCubicActionIn* clone() const override; virtual EaseCubicActionIn* reverse() const override; @@ -1045,18 +1207,20 @@ private: }; /** +@class EaseCubicActionOut @brief Ease Cubic Out @ingroup Actions */ class CC_DLL EaseCubicActionOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseCubicActionOut action. If creation failed, return nil. + */ static EaseCubicActionOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseCubicActionOut* clone() const override; virtual EaseCubicActionOut* reverse() const override; @@ -1070,18 +1234,20 @@ private: }; /** +@class EaseCubicActionInOut @brief Ease Cubic InOut @ingroup Actions */ class CC_DLL EaseCubicActionInOut : public ActionEase { public: - /** creates the action */ + /** + @brief Create the action with the inner action. + @param action The pointer of the inner action. + @return A pointer of EaseCubicActionInOut action. If creation failed, return nil. + */ static EaseCubicActionInOut* create(ActionInterval* action); - /** - * @param time in seconds - */ virtual void update(float time) override; virtual EaseCubicActionInOut* clone() const override; virtual EaseCubicActionInOut* reverse() const override; diff --git a/cocos/2d/CCActionGrid.h b/cocos/2d/CCActionGrid.h index ea38ef2337..e37f201ad0 100644 --- a/cocos/2d/CCActionGrid.h +++ b/cocos/2d/CCActionGrid.h @@ -39,12 +39,19 @@ class NodeGrid; * @{ */ -/** @brief Base class for Grid actions */ +/** +@class GridAction +@brief Base class for Grid actions. +@detail Grid actions are the actions take effect on GridBase. +*/ class CC_DLL GridAction : public ActionInterval { public: - /** returns the grid */ + /** + @brief Get the pointer of GridBase. + @return The pointer of GridBase. + */ virtual GridBase* getGrid(); // overrides @@ -60,8 +67,10 @@ CC_CONSTRUCTOR_ACCESS: GridAction() {} virtual ~GridAction() {} /** - * initializes the action with size and duration - * @param duration in seconds + * @brief Initializes the action with size and duration. + * @param duration The duration of the GridAction. It's a value in seconds. + * @param gridSize The size of the GridAction should be. + * @return Return true when the initialization success, otherwise return false. */ bool initWithDuration(float duration, const Size& gridSize); @@ -78,15 +87,18 @@ private: /** @brief Base class for Grid3D actions. - Grid3D actions can modify a non-tiled grid. + @detail Grid3D actions can modify a non-tiled grid. */ class CC_DLL Grid3DAction : public GridAction { public: - /** returns the grid */ + virtual GridBase* getGrid() override; - /** returns the vertex than belongs to certain position in the grid + /** + * @brief Get the vertex that belongs to certain position in the grid. + * @param position The position of the grid. + * @return Return a pointer of vertex. * @js NA * @lua NA */ @@ -98,7 +110,10 @@ public: */ CC_DEPRECATED_ATTRIBUTE inline Vec3 vertex(const Vec2& position) { return getVertex(position); } - /** returns the non-transformed vertex than belongs to certain position in the grid + /** + * @brief Get the non-transformed vertex that belongs to certain position in the grid. + * @param position The position of the grid. + * @return Return a pointer of vertex. * @js NA * @lua NA */ @@ -110,7 +125,10 @@ public: */ CC_DEPRECATED_ATTRIBUTE inline Vec3 originalVertex(const Vec2& position) { return getOriginalVertex(position); } - /** sets a new vertex to a certain position of the grid + /** + * @brief Set a new vertex to a certain position of the grid. + * @param position The position of the grid. + * @param vertex The vertex will be used on the certain position of grid. * @js NA * @lua NA */ @@ -124,17 +142,26 @@ public: } }; -/** @brief Base class for TiledGrid3D actions */ +/** +@brief Base class for TiledGrid3D actions +*/ class CC_DLL TiledGrid3DAction : public GridAction { public: - /** creates the action with size and duration + /** + * @brief Create the action with size and duration. + * @param duration The duration of the action. It's a value in seconds. + * @param gridSize Specify the grid size of the action. + * @return A pointer of TiledGrid3DAction. If creation failed, return nil. * @js NA * @lua NA */ static TiledGrid3DAction* create(float duration, const Size& gridSize); - /** returns the tile that belongs to a certain position of the grid + /** + * @brief Get the tile that belongs to a certain position of the grid. + * @param position The position of the tile want to get. + * @return A quadrilateral of the tile. * @js NA * @lua NA */ @@ -146,19 +173,25 @@ public: */ CC_DEPRECATED_ATTRIBUTE Quad3 tile(const Vec2& position) { return getTile(position); } - /** returns the non-transformed tile that belongs to a certain position of the grid + /** + * @brief Get the non-transformed tile that belongs to a certain position of the grid. + * @param position The position of the tile want to get. + * @return A quadrilateral of the tile. * @js NA * @lua NA */ Quad3 getOriginalTile(const Vec2& position) const; - /** @deprecated Use getOriginalTile() instead + /** @deprecated Use getOriginalTile() instead. * @js NA * @lua NA */ CC_DEPRECATED_ATTRIBUTE Quad3 originalTile(const Vec2& position) { return getOriginalTile(position); } - /** sets a new tile to a certain position of the grid + /** + * @brief Set a new tile to a certain position of the grid. + * @param position The position of the tile. + * @param coords The quadrilateral of the new tile. * @js NA * @lua NA */ @@ -175,23 +208,33 @@ public: } }; -/** @brief AccelDeccelAmplitude action */ +/** +@brief AccelDeccelAmplitude action. +*/ class CC_DLL AccelDeccelAmplitude : public ActionInterval { public: - /** creates the action with an inner action that has the amplitude property, and a duration time */ + /** + @brief Create the action with an inner action that has the amplitude property, and a duration time. + @@param action A pointer of the inner action. + @param duration Specify the duration of the AccelDeccelAmplitude action. + @return Return a pointer of AccelDeccelAmplitude action. When the creation failed, return nil. + */ static AccelDeccelAmplitude* create(Action *action, float duration); - /** get amplitude rate */ + /** + @brief Get the value of amplitude rate. + @return the value of amplitude rate. + */ inline float getRate(void) const { return _rate; } - /** set amplitude rate */ + /** + @brief Set the value of amplitude rate. + @param rate Specify the value of amplitude rate. + */ inline void setRate(float rate) { _rate = rate; } // Overrides virtual void startWithTarget(Node *target) override; - /** - * @param time in seconds - */ virtual void update(float time) override; virtual AccelDeccelAmplitude* clone() const override; virtual AccelDeccelAmplitude* reverse() const override; @@ -200,7 +243,12 @@ CC_CONSTRUCTOR_ACCESS: AccelDeccelAmplitude() {} virtual ~AccelDeccelAmplitude(); - /** initializes the action with an inner action that has the amplitude property, and a duration time */ + /** + @brief Initializes the action with an inner action that has the amplitude property, and a duration time. + @param action A pointer of the inner action. + @param duration Specify the duration of the AccelDeccelAmplitude action. + @return If the initialization success, return true; otherwise, return false. + */ bool initWithAction(Action *action, float duration); protected: @@ -211,23 +259,33 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(AccelDeccelAmplitude); }; -/** @brief AccelAmplitude action */ +/** +@brief AccelAmplitude action. +*/ class CC_DLL AccelAmplitude : public ActionInterval { public: - /** creates the action with an inner action that has the amplitude property, and a duration time */ + /** + @brief Create the action with an inner action that has the amplitude property, and a duration time. + @param action A pointer of the inner action. + @param duration Specify the duration of the AccelAmplitude action. + @return Return a pointer of AccelAmplitude action. When the creation failed, return nil. + */ static AccelAmplitude* create(Action *action, float duration); - /** get amplitude rate */ + /** + @brief Get the value of amplitude rate. + @return The value of amplitude rate. + */ inline float getRate() const { return _rate; } - /** set amplitude rate */ + /** + @brief Set the value of amplitude rate. + @param rate Specify the value of amplitude rate. + */ inline void setRate(float rate) { _rate = rate; } // Overrides virtual void startWithTarget(Node *target) override; - /** - * @param time in seconds - */ virtual void update(float time) override; virtual AccelAmplitude* clone() const override; virtual AccelAmplitude* reverse() const override; @@ -246,23 +304,33 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(AccelAmplitude); }; -/** @brief DeccelAmplitude action */ +/** +@brief DeccelAmplitude action +*/ class CC_DLL DeccelAmplitude : public ActionInterval { public: - /** creates the action with an inner action that has the amplitude property, and a duration time */ + /** + @brief Creates the action with an inner action that has the amplitude property, and a duration time. + @param action A pointer of the inner action. + @param duration Specify the duration of the DeccelAmplitude action. + @return Return a pointer of DeccelAmplitude. When the creation failed, return nil. + */ static DeccelAmplitude* create(Action *action, float duration); - /** get amplitude rate */ + /** + @brief Get the value of amplitude rate. + @return The value of amplitude rate. + */ inline float getRate() const { return _rate; } - /** set amplitude rate */ + /** + @brief Set the value of amplitude rate. + @param rate Specify the value. + */ inline void setRate(float rate) { _rate = rate; } // overrides virtual void startWithTarget(Node *target) override; - /** - * @param time in seconds - */ virtual void update(float time) override; virtual DeccelAmplitude* clone() const override; virtual DeccelAmplitude* reverse() const override; @@ -271,7 +339,12 @@ CC_CONSTRUCTOR_ACCESS: DeccelAmplitude() {} virtual ~DeccelAmplitude(); - /** initializes the action with an inner action that has the amplitude property, and a duration time */ + /** + @brief Initializes the action with an inner action that has the amplitude property, and a duration time. + @param action The pointer of inner action. + @param duration The duration of the DeccelAmplitude action. + @return If the initilization sucess, return true; otherwise, return false. + */ bool initWithAction(Action *action, float duration); protected: @@ -282,7 +355,8 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(DeccelAmplitude); }; -/** @brief StopGrid action. +/** + @brief StopGrid action. @warning Don't call this action if another grid action is active. Call if you want to remove the the grid effect. Example: Sequence::actions(Lens::action(...), StopGrid::action(...), nullptr); @@ -290,7 +364,10 @@ private: class CC_DLL StopGrid : public ActionInstant { public: - /** Allocates and initializes the action */ + /** + @brief Create a StopGrid Action. + @return Return a pointer of StopGrid. When the creation failed, return nil. + */ static StopGrid* create(); // Overrides @@ -311,11 +388,17 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(StopGrid); }; -/** @brief ReuseGrid action */ +/** +@brief ReuseGrid action. +*/ class CC_DLL ReuseGrid : public ActionInstant { public: - /** creates an action with the number of times that the current grid will be reused */ + /** + @brief Create an action with the number of times that the current grid will be reused. + @param times Specify times the grid will be reused. + @return Return a pointer of ReuseGrid. When the creation failed, return nil. + */ static ReuseGrid* create(int times); // Override @@ -327,7 +410,11 @@ CC_CONSTRUCTOR_ACCESS: ReuseGrid() {} virtual ~ReuseGrid() {} - /** initializes an action with the number of times that the current grid will be reused */ + /** + @brief Initializes an action with the number of times that the current grid will be reused. + @param times Specify times the grid will be reused. + @return If the initialization sucess, return true; otherwise, return false. + */ bool initWithTimes(int times); protected: diff --git a/cocos/2d/CCActionGrid3D.h b/cocos/2d/CCActionGrid3D.h index ea9bbec084..d357277251 100644 --- a/cocos/2d/CCActionGrid3D.h +++ b/cocos/2d/CCActionGrid3D.h @@ -36,36 +36,62 @@ NS_CC_BEGIN */ /** -@brief Waves3D action +@brief Waves3D action. +@detail This action is used for take effect on the target node as 3D waves. + You can control the effect by these parameters: + duration, grid size, waves count, amplitude. */ class CC_DLL Waves3D : public Grid3DAction { public: - /** creates an action with duration, grid size, waves and amplitude */ + /** + @brief Create an action with duration, grid size, waves and amplitude. + @param duration Specify the duration of the Waves3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the Waves3D action. + @param amplitude Specify the amplitude of the Waves3D action. + @return If the creation sucess, return a pointer of Waves3D action; otherwise, return nil. + */ static Waves3D* create(float duration, const Size& gridSize, unsigned int waves, float amplitude); - /** returns the amplitude of the effect */ + /** + @brief Get the amplitude of the effect. + @return Return the amplitude of the effect. + */ inline float getAmplitude() const { return _amplitude; } - /** sets the amplitude to the effect */ + /** + @brief Set the amplitude to the effect. + @param amplitude The value of amplitude will be set. + */ inline void setAmplitude(float amplitude) { _amplitude = amplitude; } - /** returns the amplitude rate */ + /** + @brief Get the amplitude rate of the effect. + @return Return the amplitude rate of the effect. + */ inline float getAmplitudeRate() const { return _amplitudeRate; } - /** sets the ampliture rate */ + /** + @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; } // Overrides virtual Waves3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: Waves3D() {} virtual ~Waves3D() {} - /** initializes an action with duration, grid size, waves and amplitude */ + /** + @brief Initializes an action with duration, grid size, waves and amplitude. + @param duration Specify the duration of the Waves3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the Waves3D action. + @param amplitude Specify the amplitude of the Waves3D action. + @return If the initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int waves, float amplitude); protected: @@ -77,43 +103,62 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Waves3D); }; -/** @brief FlipX3D action */ +/** +@brief FlipX3D action. +@detail This action is used for flipping the target node on the x axis. +*/ class CC_DLL FlipX3D : public Grid3DAction { public: - /** creates the action with duration */ + /** + @brief Create the action with duration. + @param duration Specify the duration of the FilpX3D action. It's a value in seconds. + @return If the creation sucess, return a pointer of FilpX3D action; otherwise, return nil. + */ static FlipX3D* create(float duration); // Override virtual FlipX3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: FlipX3D() {} virtual ~FlipX3D() {} - /** initializes the action with duration */ + /** + @brief Initializes an action with duration. + @param duration Specify the duration of the FlipX3D action. It's a value in seconds. + @return If the initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration); + + /** + @brief Initializes an action with duration and grid size. + @param gridSize Specify the grid size of the FlipX3D action. + @param duration Specify the duration of the FlipX3D action. It's a value in seconds. + @return If the initialization success, return true; otherwise, return false. + */ virtual bool initWithSize(const Size& gridSize, float duration); private: CC_DISALLOW_COPY_AND_ASSIGN(FlipX3D); }; -/** @brief FlipY3D action */ +/** +@brief FlipY3D action. +@detail This action is used for flipping the target node on the y axis. +*/ class CC_DLL FlipY3D : public FlipX3D { public: - /** creates the action with duration */ + /** + @brief Create the action with duration. + @param duration Specify the duration of the FlipY3D action. It's a value in seconds. + @return If the creation sucess, return a pointer of FlipY3D action; otherwise, return nil. + */ static FlipY3D* create(float duration); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual FlipY3D* clone() const override; @@ -124,35 +169,72 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FlipY3D); }; -/** @brief Lens3D action */ +/** +@brief Lens3D action. +@detail This action is used for take effect on the target node as lens. + You can create the action by these parameters: + duration, grid size, center position of lens, radius of lens. + Also you can change the lens effect value & whether effect is concave by the setter methods. +*/ class CC_DLL Lens3D : public Grid3DAction { public: - /** creates the action with center position, radius, a grid size and duration */ + /** + @brief Create the action with center position, radius, a grid size and duration. + @param duration Specify the duration of the Lens3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param position Specify the center position of the lens. + @param radius Specify the radius of the lens. + @return If the creation sucess, return a pointer of Lens3D action; otherwise, return nil. + */ static Lens3D* create(float duration, const Size& gridSize, const Vec2& position, float radius); - /** Get lens center position */ + /** + @brief Get the value of lens effect. Default value is 0.7. + @return The value of lens effect. + */ inline float getLensEffect() const { return _lensEffect; } - /** Set lens center position */ + + /** + @brief Set the value of lens effect. + @param lensEffect The value of lens effect will be set. + */ inline void setLensEffect(float lensEffect) { _lensEffect = lensEffect; } - /** Set whether lens is concave */ + + /** + @brief Set whether lens is concave. + @param concave Whether lens is concave. + */ inline void setConcave(bool concave) { _concave = concave; } - + + /** + @brief Get the center position of lens effect. + @return The center position of lens effect. + */ inline const Vec2& getPosition() const { return _position; } + + /** + @brief Set the center position of lens effect. + @param The center position will be set. + */ void setPosition(const Vec2& position); // Overrides virtual Lens3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: Lens3D() {} virtual ~Lens3D() {} - /** initializes the action with center position, radius, a grid size and duration */ + /** + @brief Initializes the action with center position, radius, grid size and duration. + @param duration Specify the duration of the Lens3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param position Specify the center position of the lens effect. + @param radius Specify the radius of the lens effect. + @return If the initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, const Vec2& position, float radius); protected: @@ -170,36 +252,79 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Lens3D); }; -/** @brief Ripple3D action */ +/** +@brief Ripple3D action. +@detail This action is used for take effect on the target node as ripple. + You can create the action by these parameters: + duration, grid size, center position of ripple, + radius of ripple, waves count, amplitude. +*/ class CC_DLL Ripple3D : public Grid3DAction { public: - /** creates the action with radius, number of waves, amplitude, a grid size and duration */ + /** + @brief Create the action with center position, radius, number of waves, amplitude, a grid size and duration. + @param duration Specify the duration of the Ripple3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param position Specify the center position of the ripple effect. + @param radius Specify the radius of the ripple effect. + @param waves Specify the waves count of the ripple effect. + @param amplitude Specify the amplitude of the ripple effect. + @return If the creation sucess, return a pointer of Ripple3D action; otherwise, return nil. + */ static Ripple3D* create(float duration, const Size& gridSize, const Vec2& position, float radius, unsigned int waves, float amplitude); - /** get center position */ + /** + @brief Get the center position of ripple effect. + @return The center position of ripple effect. + */ inline const Vec2& getPosition() const { return _position; } - /** set center position */ + /** + @brief Set the center position of ripple effect. + @param position The center position of ripple effect will be set. + */ void setPosition(const Vec2& position); + /** + @brief Get the amplitude of ripple effect. + @return The amplitude of ripple effect. + */ inline float getAmplitude() const { return _amplitude; } + /** + @brief Set the amplitude of ripple effect. + @param fAmplitude The amplitude of ripple effect. + */ inline void setAmplitude(float fAmplitude) { _amplitude = fAmplitude; } + /** + @brief Get the amplitude rate of ripple effect. + @return The amplitude rate of ripple effect. + */ inline float getAmplitudeRate() const { return _amplitudeRate; } + /** + @brief Set the amplitude rate of ripple effect. + @param fAmplitudeRate The amplitude rate of ripple effect. + */ inline void setAmplitudeRate(float fAmplitudeRate) { _amplitudeRate = fAmplitudeRate; } // Override virtual Ripple3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: Ripple3D() {} virtual ~Ripple3D() {} - /** initializes the action with radius, number of waves, amplitude, a grid size and duration */ + /** + @brief Initializes the action with center position, radius, number of waves, amplitude, a grid size and duration. + @param duration Specify the duration of the Ripple3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param position Specify the center position of the ripple effect. + @param radius Specify the radius of the ripple effect. + @param waves Specify the waves count of the ripple effect. + @param amplitude Specify the amplitude of the ripple effect. + @return If the initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, const Vec2& position, float radius, unsigned int waves, float amplitude); protected: @@ -214,12 +339,24 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Ripple3D); }; -/** @brief Shaky3D action */ +/** +@brief Shaky3D action. +@detail This action is used for take effect on the target node as shaky. + You can create the action by these parameters: + duration, grid size, range, whether shake on the z axis. +*/ class CC_DLL Shaky3D : public Grid3DAction { public: - /** creates the action with a range, shake Z vertices, a grid and duration */ - static Shaky3D* create(float duration, const Size& gridSize, int range, bool shakeZ); + /** + @brief Create the action with a range, shake Z vertices, a grid and duration. + @param duration Specify the duration of the Shaky3D 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 sucess, return a pointer of Shaky3D action; otherwise, return nil. + */ + static Shaky3D* create(float initWithDuration, const Size& gridSize, int range, bool shakeZ); // Overrides virtual Shaky3D* clone() const override; @@ -230,9 +367,13 @@ CC_CONSTRUCTOR_ACCESS: virtual ~Shaky3D() {} /** - * initializes the action with a range, shake Z vertices, a grid 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 Shaky3D 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 sucess, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, int range, bool shakeZ); protected: @@ -243,31 +384,63 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Shaky3D); }; -/** @brief Liquid action */ +/** +@brief Liquid action. +@detail This action is used for take effect on the target node as liquid. + You can create the action by these parameters: + duration, grid size, waves count, amplitude of the liquid effect. +*/ class CC_DLL Liquid : public Grid3DAction { public: - /** creates the action with amplitude, a grid and duration */ + /** + @brief Create the action with amplitude, grid size, waves count and duration. + @param duration Specify the duration of the Liquid action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the Liquid action. + @param amplitude Specify the amplitude of the Liquid action. + @return If the creation sucess, return a pointer of Liquid action; otherwise, return nil. + */ static Liquid* create(float duration, const Size& gridSize, unsigned int waves, float 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; } + /** + @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; } // Overrides virtual Liquid* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: Liquid() {} virtual ~Liquid() {} - /** initializes the action with amplitude, a grid and duration */ + /** + @brief Initializes the action with amplitude, grid size, waves count and duration. + @param duration Specify the duration of the Liquid action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the Liquid action. + @param amplitude Specify the amplitude of the Liquid action. + @return If the initialization sucess, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int waves, float amplitude); protected: @@ -279,31 +452,68 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Liquid); }; -/** @brief Waves action */ +/** +@brief Waves action. +@detail This action is used for take effect on the target node as waves. + You can control the effect by these parameters: + duration, grid size, waves count, amplitude, + whether waves on horizontal and whether waves on vertical. +*/ class CC_DLL Waves : public Grid3DAction { public: - /** initializes the action with amplitude, horizontal sin, vertical sin, a grid and duration */ + /** + @brief Create the action with amplitude, horizontal sin, vertical sin, grid size, waves count and duration. + @param duration Specify the duration of the Waves action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the Waves action. + @param amplitude Specify the amplitude of the Waves action. + @param horizontal Specify whether waves on horizontal. + @param vertical Specify whether waves on vertical. + @return If the creation sucess, return a pointer of Waves action; otherwise, return nil. + */ static Waves* create(float duration, const Size& gridSize, unsigned int waves, float amplitude, bool horizontal, bool vertical); + /** + @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; } + /** + @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; } // Overrides virtual Waves* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: Waves() {} virtual ~Waves() {} - /** initializes the action with amplitude, horizontal sin, vertical sin, a grid and duration */ + /** + @brief Initializes the action with amplitude, horizontal sin, vertical sin, grid size, waves count and duration. + @param duration Specify the duration of the Waves action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the Waves action. + @param amplitude Specify the amplitude of the Waves action. + @param horizontal Specify whether waves on horizontal. + @param vertical Specify whether waves on vertical. + @return If the initialization sucess, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int waves, float amplitude, bool horizontal, bool vertical); protected: @@ -317,37 +527,77 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Waves); }; -/** @brief Twirl action */ +/** +@brief Twirl action. +@detail This action is used for take effect on the target node as twirl. + You can control the effect by these parameters: + duration, grid size, center position, twirls count, amplitude. +*/ class CC_DLL Twirl : public Grid3DAction { public: - /** creates the action with center position, number of twirls, amplitude, a grid size and duration */ + /** + @brief Create the action with center position, number of twirls, amplitude, a grid size and duration. + @param duration Specify the duration of the Twirl action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param position Specify the center position of the twirl action. + @param twirls Specify the twirls count of the Twirl action. + @param amplitude Specify the amplitude of the Twirl action. + @return If the creation sucess, return a pointer of Twirl action; otherwise, return nil. + */ static Twirl* create(float duration, const Size& gridSize, Vec2 position, unsigned int twirls, float amplitude); - /** get twirl center */ + /** + @brief Get the center position of twirl action. + @return The center position of twirl action. + */ inline const Vec2& getPosition() const { return _position; } - /** set twirl center */ + /** + @brief Set the center position of twirl action. + @param position The center position of twirl action will be set. + */ void setPosition(const Vec2& position); + /** + @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; } + /** + @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; } // Overrides virtual Twirl* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: Twirl() {} virtual ~Twirl() {} - - /** initializes the action with center position, number of twirls, amplitude, a grid size and duration */ + + /** + @brief Initializes the action with center position, number of twirls, amplitude, a grid size and duration. + @param duration Specify the duration of the Twirl action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param position Specify the center position of the twirl action. + @param twirls Specify the twirls count of the Twirl action. + @param amplitude Specify the amplitude of the Twirl action. + @return If the initialization sucess, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, Vec2 position, unsigned int twirls, float amplitude); protected: diff --git a/cocos/2d/CCActionPageTurn3D.h b/cocos/2d/CCActionPageTurn3D.h index 40758f6444..e195ae97ba 100644 --- a/cocos/2d/CCActionPageTurn3D.h +++ b/cocos/2d/CCActionPageTurn3D.h @@ -37,10 +37,10 @@ NS_CC_BEGIN /** @brief This action simulates a page turn from the bottom right hand corner of the screen. - It's not much use by itself but is used by the PageTurnTransition. - Based on an original paper by L Hong et al. - http://www.parc.com/publication/1638/turning-pages-of-3d-electronic-books.html + @detail It's not much use by itself but is used by the PageTurnTransition. + Based on an original paper by L Hong et al. + http://www.parc.com/publication/1638/turning-pages-of-3d-electronic-books.html @since v0.8.2 */ @@ -48,14 +48,17 @@ class CC_DLL PageTurn3D : public Grid3DAction { public: virtual GridBase* getGrid() override; - /** create the action */ + + /** + @brief Create an action with duration, grid size. + @param duration Specify the duration of the PageTurn3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @return If the creation sucess, return a pointer of PageTurn3D action; otherwise, return nil. + */ static PageTurn3D* create(float duration, const Size& gridSize); // Overrides virtual PageTurn3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; }; diff --git a/cocos/2d/CCActionProgressTimer.h b/cocos/2d/CCActionProgressTimer.h index ea5453a181..67542ebee1 100644 --- a/cocos/2d/CCActionProgressTimer.h +++ b/cocos/2d/CCActionProgressTimer.h @@ -36,15 +36,19 @@ NS_CC_BEGIN */ /** -@brief Progress to percentage +@brief Progress to percentage. +@detail This action show the target node from current percentage to the specified percentage. + You should specify the destination percentage when creating the action. @since v0.99.1 */ class CC_DLL ProgressTo : public ActionInterval { public: /** - * Creates and initializes with a duration and a percent - * @param duration in seconds + * @brief Create and initializes with a duration and a destination percentage. + * @param duration Specify the duration of the ProgressTo action. It's a value in seconds. + * @param percent Specify the destination percentage. + * @return If the creation sucess, return a pointer of ProgressTo action; otherwise, return nil. */ static ProgressTo* create(float duration, float percent); @@ -54,9 +58,6 @@ public: virtual ProgressTo* clone() const override; virtual ProgressTo* reverse() const override; virtual void startWithTarget(Node *target) override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: @@ -64,8 +65,10 @@ CC_CONSTRUCTOR_ACCESS: virtual ~ProgressTo() {} /** - * Initializes with a duration and a percent - * @param duration in seconds + * @brief Initializes with a duration and destination percentage. + * @param duration Specify the duration of the ProgressTo action. It's a value in seconds. + * @param percent Specify the destination percentage. + * @return If the creation sucess, return true; otherwise, return false. */ bool initWithDuration(float duration, float percent); @@ -78,15 +81,18 @@ private: }; /** -@brief Progress from a percentage to another percentage +@brief Progress from a percentage to another percentage. @since v0.99.1 */ class CC_DLL ProgressFromTo : public ActionInterval { public: /** - * Creates and initializes the action with a duration, a "from" percentage and a "to" percentage - * @param duration in seconds + * @brief Create and initializes the action with a duration, a "from" percentage and a "to" percentage. + * @param duration Specify the duration of the ProgressFromTo action. It's a value in seconds. + * @param fromPercentage Specify the source percentage. + * @param toPercentage Specify the destination percentage. + * @return If the creation sucess, return a pointer of ProgressFromTo action; otherwise, return nil. */ static ProgressFromTo* create(float duration, float fromPercentage, float toPercentage); @@ -96,16 +102,19 @@ public: virtual ProgressFromTo* clone() const override; virtual ProgressFromTo* reverse() const override; virtual void startWithTarget(Node *target) override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: ProgressFromTo() {} virtual ~ProgressFromTo() {} - /** Initializes the action with a duration, a "from" percentage and a "to" percentage */ + /** + * @brief Initializes the action with a duration, a "from" percentage and a "to" percentage. + * @param duration Specify the duration of the ProgressFromTo action. It's a value in seconds. + * @param fromPercentage Specify the source percentage. + * @param toPercentage Specify the destination percentage. + * @return If the creation sucess, return true; otherwise, return false. + */ bool initWithDuration(float duration, float fromPercentage, float toPercentage); protected: diff --git a/cocos/2d/CCActionTween.h b/cocos/2d/CCActionTween.h index 9b28d180ab..17bef18dc0 100644 --- a/cocos/2d/CCActionTween.h +++ b/cocos/2d/CCActionTween.h @@ -35,6 +35,15 @@ NS_CC_BEGIN * @{ */ +/** +@brief The delegate class for ActionTween. +@detail If you want to use ActionTween on a node. + You should implement the node follow these steps: + 1. The node should be inherit from ActionTweenDelegate. + 2. Override the virtual method updateTweenAction in the node. + + Then once you running ActionTween on the node, the method updateTweenAction will be incoked. +*/ class CC_DLL ActionTweenDelegate { public: @@ -43,6 +52,12 @@ public: * @lua NA */ virtual ~ActionTweenDelegate() {} + + /** + @brief The callback function when ActionTween is running. + @param value The new value of the specified key. + @param key The key of property which should be updated. + */ virtual void updateTweenAction(float value, const std::string& key) = 0; }; @@ -70,24 +85,29 @@ class CC_DLL ActionTween : public ActionInterval { public: /** - * creates an initializes the action with the property name (key), and the from and to parameters. - * @param duration in seconds + * @brief Create and initializes the action with the property name (key), and the from and to parameters. + * @param duration The duration of the ActionTween. It's a value in seconds. + * @param key The key of property which should be updated. + * @param from The value of the specified property when the action begin. + * @param to The value of the specified property when the action end. + * @return If the creation success, return a pointer of ActionTween; otherwise, return nil. */ static ActionTween* create(float duration, const std::string& key, float from, float to); // Overrides void startWithTarget(Node *target) override; - /** - * @param dt in seconds - */ void update(float dt) override; ActionTween* reverse() const override; ActionTween *clone() const override; CC_CONSTRUCTOR_ACCESS: /** - * initializes the action with the property name (key), and the from and to parameters. - * @param duration in seconds + * @brief Initializes the action with the property name (key), and the from and to parameters. + * @param duration The duration of the ActionTween. It's a value in seconds. + * @param key The key of property which should be updated. + * @param from The value of the specified property when the action begin. + * @param to The value of the specified property when the action end. + * @return If the initialization success, return true; otherwise, return false. */ bool initWithDuration(float duration, const std::string& key, float from, float to); From f0a8fcd282bdfebd909fac4ea064b5a6f8d81b78 Mon Sep 17 00:00:00 2001 From: CocosRobot Date: Wed, 18 Mar 2015 10:28:24 +0000 Subject: [PATCH 26/32] [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 4ae4500a686ff7af5d630fb0fe7437b46e7cc14f Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 19:32:10 +0800 Subject: [PATCH 27/32] [ci skip]adjust comments --- cocos/renderer/CCVertexIndexBuffer.h | 12 ++++++++-- cocos/renderer/CCVertexIndexData.h | 36 +++++++++++++++++++++++++--- 2 files changed, 43 insertions(+), 5 deletions(-) diff --git a/cocos/renderer/CCVertexIndexBuffer.h b/cocos/renderer/CCVertexIndexBuffer.h index 74fde4ddf7..0a615dc991 100644 --- a/cocos/renderer/CCVertexIndexBuffer.h +++ b/cocos/renderer/CCVertexIndexBuffer.h @@ -121,9 +121,12 @@ protected: static bool _enableShadowCopy; public: /** - Static getter/setter for shadowCopy. + Static getter for shadowCopy. */ static bool isShadowCopyEnabled() { return _enableShadowCopy; } + /** + Static setter for shadowCopy. + */ static void enableShadowCopy(bool enabled) { _enableShadowCopy = enabled; } }; @@ -139,7 +142,9 @@ public: */ enum class IndexType { + /**Short index will be used.*/ INDEX_TYPE_SHORT_16, + /**Int index will be used.*/ INDEX_TYPE_UINT_32 }; @@ -234,9 +239,12 @@ protected: static bool _enableShadowCopy; public: /** - Static getter/setter for shadowCopy. + Static getter for shadowCopy. */ static bool isShadowCopyEnabled() { return _enableShadowCopy; } + /** + Static setter for shadowCopy. + */ static void enableShadowCopy(bool enabled) { _enableShadowCopy = enabled; } }; diff --git a/cocos/renderer/CCVertexIndexData.h b/cocos/renderer/CCVertexIndexData.h index d336db4e35..94f77320d4 100644 --- a/cocos/renderer/CCVertexIndexData.h +++ b/cocos/renderer/CCVertexIndexData.h @@ -45,25 +45,55 @@ glVertexAttribPointer(GLuint indx, GLint size, GLenum type, GLboolean normalized */ struct CC_DLL VertexStreamAttribute { + /** + Constructor. + */ VertexStreamAttribute() : _normalize(false),_offset(0),_semantic(0),_type(0),_size(0) { } - + /** + Constructor + @param offset The offset of the attribute. + @param semantic The semantic (Position, Texcoord, Color etc) of attribute. + @param type The type of attribute, could be GL_FLOAT, GL_UNSIGNED_BYTE etc. + @param size Describe how many elements of type in the attribute. + */ VertexStreamAttribute(int offset, int semantic, int type, int size) : _normalize(false),_offset(offset),_semantic(semantic),_type(type),_size(size) { } - + /** + Constructor + @param offset The offset of the attribute. + @param semantic The semantic (Position, Texcoord, Color etc) of attribute. + @param type The type of attribute, could be GL_FLOAT, GL_UNSIGNED_BYTE etc. + @param size Describe how many elements of type in the attribute. + @param normalize If true, the data will be normalized by deviding 255. + */ VertexStreamAttribute(int offset, int semantic, int type, int size, bool normalize) : _normalize(normalize),_offset(offset),_semantic(semantic),_type(type),_size(size) { } - + /** + Whether the attribute should be normalized or not. + */ bool _normalize; + /** + The offset of the attribute in the buffer. + */ int _offset; + /** + Describe that the attribute usage, could be Position, Color etc. + */ int _semantic; + /** + Describe the type of attribute, could be GL_FLOAT, GL_UNSIGNED_BYTE etc. + */ int _type; + /** + Describe how many elements of type in the attribute. + */ int _size; }; From a87c5755e9f77945fe7d90c47bd46ebb90a99710 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 19:52:08 +0800 Subject: [PATCH 28/32] [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 ee8776f041958f7cc3174adb403bf96f3ec6c72b Mon Sep 17 00:00:00 2001 From: SuYaohui <365886954@qq.com> Date: Wed, 18 Mar 2015 20:05:59 +0800 Subject: [PATCH 29/32] [ci skip]Action,ActionCamera,ActionCatmullRom,Animation,AnimationCache,AtlasNode --- cocos/2d/CCAction.h | 182 +++++++++++++++++++++++----------- cocos/2d/CCActionCamera.h | 70 +++++++++---- cocos/2d/CCActionCatmullRom.h | 155 +++++++++++++++++++---------- cocos/2d/CCAnimation.h | 164 ++++++++++++++++++++---------- cocos/2d/CCAnimationCache.h | 55 +++++----- cocos/2d/CCAtlasNode.h | 54 ++++++---- 6 files changed, 452 insertions(+), 228 deletions(-) diff --git a/cocos/2d/CCAction.h b/cocos/2d/CCAction.h index 384a6c9631..b73de3e2bc 100644 --- a/cocos/2d/CCAction.h +++ b/cocos/2d/CCAction.h @@ -40,12 +40,12 @@ class Node; */ /** -@brief Base class for Action objects. + * @brief Base class for Action objects. */ class CC_DLL Action : public Ref, public Clonable { public: - /// Default tag used for all the actions + /** Default tag used for all the actions. */ static const int INVALID_TAG = -1; /** * @js NA @@ -53,58 +53,94 @@ public: */ virtual std::string description() const; - /** returns a clone of action */ + /** Returns a clone of action. + * + * @return A clone action. + */ virtual Action* clone() const { CC_ASSERT(0); return nullptr; } - /** returns a new action that performs the exactly the reverse action */ + /** Returns a new action that performs the exactly the reverse action. + * + * @return A new action that performs the exactly the reverse action. + */ virtual Action* reverse() const { CC_ASSERT(0); return nullptr; } - //! return true if the action has finished + /** Return true if the action has finished. + * + * @return Is true if the action has finished. + */ virtual bool isDone() const; - //! called before the action start. It will also set the target. + /** Called before the action start. It will also set the target. + * + * @param target A certain target. + */ virtual void startWithTarget(Node *target); /** - called after the action has finished. It will set the 'target' to nil. - IMPORTANT: You should never call "[action stop]" manually. Instead, use: "target->stopAction(action);" - */ + * Called after the action has finished. It will set the 'target' to nil. + * IMPORTANT: You should never call "Action::stop()" manually. Instead, use: "target->stopAction(action);". + */ virtual void stop(); - //! called every frame with it's delta time, dt in seconds. DON'T override unless you know what you are doing. + /** Called every frame with it's delta time, dt in seconds. DON'T override unless you know what you are doing. + * + * @param dt In seconds. + */ virtual void step(float dt); /** - called once per frame. time a value between 0 and 1 + * Called once per frame. time a value between 0 and 1. - For example: - - 0 means that the action just started - - 0.5 means that the action is in the middle - - 1 means that the action is over - */ + * For example: + * - 0 Means that the action just started. + * - 0.5 Means that the action is in the middle. + * - 1 Means that the action is over. + * + * @param time A value between 0 and 1. + */ virtual void update(float time); - + /** Return certain target.. + * + * @return A certain target. + */ inline Node* getTarget() const { return _target; } - /** The action will modify the target properties. */ + /** The action will modify the target properties. + * + * @param target A certain target. + */ inline void setTarget(Node *target) { _target = target; } - + /** Return a original Target. + * + * @return A original Target. + */ inline Node* getOriginalTarget() const { return _originalTarget; } - /** Set the original target, since target can be nil. - Is the target that were used to run the action. Unless you are doing something complex, like ActionManager, you should NOT call this method. - The target is 'assigned', it is not 'retained'. - @since v0.8.2 - */ + /** + * Set the original target, since target can be nil. + * Is the target that were used to run the action. Unless you are doing something complex, like ActionManager, you should NOT call this method. + * The target is 'assigned', it is not 'retained'. + * @since v0.8.2 + * + * @param originalTarget Is 'assigned', it is not 'retained'. + */ inline void setOriginalTarget(Node *originalTarget) { _originalTarget = originalTarget; } - + /** Returns a tag that is used to identify the action easily. + * + * @return A tag. + */ inline int getTag() const { return _tag; } + /** Changes the tag that is used to identify the action easily. + * + * @param tag Used to identify the action easily. + */ inline void setTag(int tag) { _tag = tag; } CC_CONSTRUCTOR_ACCESS: @@ -113,34 +149,40 @@ CC_CONSTRUCTOR_ACCESS: protected: Node *_originalTarget; - /** The "target". - The target will be set with the 'startWithTarget' method. - When the 'stop' method is called, target will be set to nil. - The target is 'assigned', it is not 'retained'. - */ + /** + * The "target". + * The target will be set with the 'startWithTarget' method. + * When the 'stop' method is called, target will be set to nil. + * The target is 'assigned', it is not 'retained'. + */ Node *_target; - /** The action tag. An identifier of the action */ + /** The action tag. An identifier of the action. */ int _tag; private: CC_DISALLOW_COPY_AND_ASSIGN(Action); }; -/** -@brief - Base class actions that do have a finite time duration. - Possible actions: - - An action with a duration of 0 seconds - - An action with a duration of 35.5 seconds - - Infinite time actions are valid +/** @class FiniteTimeAction + * @brief + * Base class actions that do have a finite time duration. + * Possible actions: + * - An action with a duration of 0 seconds. + * - An action with a duration of 35.5 seconds. + * Infinite time actions are valid. */ class CC_DLL FiniteTimeAction : public Action { public: - //! get duration in seconds of the action + /** Get duration in seconds of the action. + * + * @return The duration in seconds of the action. + */ inline float getDuration() const { return _duration; } - //! set duration in seconds of the action + /** Set duration in seconds of the action. + * + * @param duration In seconds of the action. + */ inline void setDuration(float duration) { _duration = duration; } // @@ -164,7 +206,7 @@ CC_CONSTRUCTOR_ACCESS: virtual ~FiniteTimeAction(){} protected: - //! duration in seconds + //! Duration in seconds. float _duration; private: @@ -174,25 +216,41 @@ private: class ActionInterval; class RepeatForever; -/** - @brief Changes the speed of an action, making it take longer (speed>1) - or less (speed<1) time. - Useful to simulate 'slow motion' or 'fast forward' effect. - @warning This action can't be Sequenceable because it is not an IntervalAction +/** @class Speed + * @brief Changes the speed of an action, making it take longer (speed>1) + * or less (speed<1) time. + * Useful to simulate 'slow motion' or 'fast forward' effect. + * @warning This action can't be Sequenceable because it is not an IntervalAction. */ class CC_DLL Speed : public Action { public: - /** create the action */ + /** Create the action and set the speed. + * + * @param action An action. + * @param speed The action speed. + */ static Speed* create(ActionInterval* action, float speed); - + /** Return the speed. + * + * @return The action speed. + */ inline float getSpeed(void) const { return _speed; } - /** alter the speed of the inner function in runtime */ + /** Alter the speed of the inner function in runtime. + * + * @param speed Alter the speed of the inner function in runtime. + */ inline void setSpeed(float speed) { _speed = speed; } - + /** Replace the interior action. + * + * @param action The new action, it will replace the running action. + */ void setInnerAction(ActionInterval *action); - + /** Return the interior action. + * + * @return The interior action. + */ inline ActionInterval* getInnerAction() const { return _innerAction; } // @@ -206,12 +264,16 @@ public: * @param dt in seconds. */ virtual void step(float dt) override; + /** Return true if the action has finished. + * + * @return Is true if the action has finished. + */ virtual bool isDone() const override; CC_CONSTRUCTOR_ACCESS: Speed(); virtual ~Speed(void); - /** initializes the action */ + /** Initializes the action. */ bool initWithAction(ActionInterval *action, float speed); protected: @@ -244,9 +306,9 @@ public: * with no boundary. */ static Follow* create(Node *followedNode, const Rect& rect = Rect::ZERO); - + /** Return boundarySet.*/ inline bool isBoundarySet() const { return _boundarySet; } - /** alter behavior - turn on/off boundary */ + /** Alter behavior - turn on/off boundary. */ inline void setBoundarySet(bool value) { _boundarySet = value; } CC_DEPRECATED_ATTRIBUTE inline void setBoudarySet(bool value) { setBoundarySet(value); } @@ -292,20 +354,20 @@ CC_CONSTRUCTOR_ACCESS: bool initWithTarget(Node *followedNode, const Rect& rect = Rect::ZERO); protected: - // node to follow + /** Node to follow. */ Node *_followedNode; - // whether camera should be limited to certain area + /** Whether camera should be limited to certain area. */ bool _boundarySet; - // if screen size is bigger than the boundary - update not needed + /** If screen size is bigger than the boundary - update not needed. */ bool _boundaryFullyCovered; - // fast access to the screen dimensions + /** Fast access to the screen dimensions. */ Vec2 _halfScreenSize; Vec2 _fullScreenSize; - // world boundaries + /** World boundaries. */ float _leftBoundary; float _rightBoundary; float _topBoundary; diff --git a/cocos/2d/CCActionCamera.h b/cocos/2d/CCActionCamera.h index d5a0caf188..e322531d7f 100644 --- a/cocos/2d/CCActionCamera.h +++ b/cocos/2d/CCActionCamera.h @@ -40,10 +40,10 @@ class Camera; * @{ */ -/** -@brief Base class for Camera actions -@ingroup Actions -*/ +/** + *@brief Base class for Camera actions. + *@ingroup Actions + */ class CC_DLL ActionCamera : public ActionInterval // { public: @@ -62,18 +62,36 @@ public: virtual ActionCamera * reverse() const override; virtual ActionCamera *clone() const override; - /* sets the Eye value of the Camera */ + /* Sets the Eye value of the Camera. + * + * @param eye The Eye value of the Camera. + */ void setEye(const Vec3 &eye); void setEye(float x, float y, float z); - /* returns the Eye value of the Camera */ + /* Returns the Eye value of the Camera. + * + * @return The Eye value of the Camera. + */ const Vec3& getEye() const { return _eye; } - /* sets the Center value of the Camera */ + /* Sets the Center value of the Camera. + * + * @param center The Center value of the Camera. + */ void setCenter(const Vec3 ¢er); - /* returns the Center value of the Camera */ + /* Returns the Center value of the Camera. + * + * @return The Center value of the Camera. + */ const Vec3& getCenter() const { return _center; } - /* sets the Up value of the Camera */ + /* Sets the Up value of the Camera. + * + * @param up The Up value of the Camera. + */ void setUp(const Vec3 &up); - /* Returns the Up value of the Camera */ + /* Returns the Up value of the Camera. + * + * @return The Up value of the Camera. + */ const Vec3& getUp() const { return _up; } protected: @@ -86,18 +104,34 @@ protected: Vec3 _up; }; -/** -@brief OrbitCamera action -Orbits the camera around the center of the screen using spherical coordinates -@ingroup Actions -*/ +/** @class OrbitCamera + * + * @brief OrbitCamera action. + * Orbits the camera around the center of the screen using spherical coordinates. + * @ingroup Actions + */ class CC_DLL OrbitCamera : public ActionCamera // { public: - /** creates a OrbitCamera action with radius, delta-radius, z, deltaZ, x, deltaX */ + /** Creates a OrbitCamera action with radius, delta-radius, z, deltaZ, x, deltaX. + * + * @param t Duration in seconds. + * @param radius The start radius. + * @param deltaRadius The delta radius. + * @param angelZ The start Angel in Z. + * @param deltaAngleZ The delta angle in Z. + * @param angelX The start Angel in X. + * @param deltaAngleX The delta angle in X. + * @return An OrbitCamera. + */ static OrbitCamera* create(float t, float radius, float deltaRadius, float angleZ, float deltaAngleZ, float angleX, float deltaAngleX); - /** positions the camera according to spherical coordinates */ + /** Positions the camera according to spherical coordinates. + * + * @param r The spherical radius. + * @param zenith The spherical zenith. + * @param azimuth The spherical azimuth. + */ void sphericalRadius(float *r, float *zenith, float *azimuth); // Overrides @@ -116,7 +150,7 @@ CC_CONSTRUCTOR_ACCESS: */ virtual ~OrbitCamera(); - /** initializes a OrbitCamera action with radius, delta-radius, z, deltaZ, x, deltaX */ + /** Initializes a OrbitCamera action with radius, delta-radius, z, deltaZ, x, deltaX. */ bool initWithDuration(float t, float radius, float deltaRadius, float angleZ, float deltaAngleZ, float angleX, float deltaAngleX); protected: diff --git a/cocos/2d/CCActionCatmullRom.h b/cocos/2d/CCActionCatmullRom.h index ec846ef834..a6e71cf56a 100644 --- a/cocos/2d/CCActionCatmullRom.h +++ b/cocos/2d/CCActionCatmullRom.h @@ -50,15 +50,16 @@ class Node; */ /** An Array that contain control points. - Used by CardinalSplineTo and (By) and CatmullRomTo (and By) actions. -@ingroup Actions + * Used by CardinalSplineTo and (By) and CatmullRomTo (and By) actions. + * @ingroup Actions */ class CC_DLL PointArray : public Ref, public Clonable { public: - /** creates and initializes a Points array with capacity + /** Creates and initializes a Points array with capacity. * @js NA + * @param capacity The size of the array. */ static PointArray* create(ssize_t capacity); @@ -73,47 +74,67 @@ public: */ PointArray(); - /** initializes a Catmull Rom config with a capacity hint + /** Initializes a Catmull Rom config with a capacity hint. + * * @js NA + * @param capacity The size of the array. + * @return True. */ bool initWithCapacity(ssize_t capacity); - /** appends a control point + /** Appends a control point. + * * @js NA + * @param controlPoint A control point. */ void addControlPoint(Vec2 controlPoint); - /** inserts a controlPoint at index + /** Inserts a controlPoint at index. + * * @js NA + * @param controlPoint A control point. + * @param index Insert the point to array in index. */ void insertControlPoint(Vec2 &controlPoint, ssize_t index); - /** replaces an existing controlPoint at index + /** Replaces an existing controlPoint at index. + * * @js NA + * @param controlPoint A control point. + * @param index Replace the point to array in index. */ void replaceControlPoint(Vec2 &controlPoint, ssize_t index); - /** get the value of a controlPoint at a given index + /** Get the value of a controlPoint at a given index. + * * @js NA + * @param index Get the point in index. + * @return A Vec2. */ Vec2 getControlPointAtIndex(ssize_t index); - /** deletes a control point at a given index + /** Deletes a control point at a given index + * * @js NA + * @param index Remove the point in index. */ void removeControlPointAtIndex(ssize_t index); - /** returns the number of objects of the control point array + /** Returns the number of objects of the control point array. + * * @js NA + * @return The number of objects of the control point array. */ ssize_t count() const; - /** returns a new copy of the array reversed. User is responsible for releasing this copy + /** Returns a new copy of the array reversed. User is responsible for releasing this copy. + * * @js NA + * @return A new copy of the array reversed. */ PointArray* reverse() const; - /** reverse the current control point array inline, without generating a new one + /** Reverse the current control point array inline, without generating a new one. * @js NA */ void reverseInline(); @@ -131,24 +152,27 @@ public: */ void setControlPoints(std::vector *controlPoints); private: - /** Array that contains the control points */ + /** Array that contains the control points. */ std::vector *_controlPoints; }; -/** Cardinal Spline path. - http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Cardinal_spline -@ingroup Actions +/** @class CardinalSplineTo + * Cardinal Spline path. + * http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Cardinal_spline + * @ingroup Actions */ class CC_DLL CardinalSplineTo : public ActionInterval { public: - /** creates an action with a Cardinal Spline array of points and tension - * @param duration in seconds + /** Creates an action with a Cardinal Spline array of points and tension. + * @param duration In seconds. + * @param point An PointArray. + * @param tension Goodness of fit. * @code - * 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) + * 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 */ static CardinalSplineTo* create(float duration, PointArray* points, float tension); @@ -164,13 +188,22 @@ public: CardinalSplineTo(); /** - * initializes the action with a duration and an array of points - * @param duration in seconds + * Initializes the action with a duration and an array of points. + * + * @param duration In seconds. + * @param point An PointArray. + * @param tension Goodness of fit. */ bool initWithDuration(float duration, PointArray* points, float tension); - + /** It will update the target position and change the _previousPosition to newPos + * + * @param newPos The new position. + */ virtual void updatePosition(Vec2 &newPos); - + /** Return a PointArray. + * + * @return A PointArray. + */ inline PointArray* getPoints() { return _points; } /** * @js NA @@ -189,7 +222,7 @@ public: virtual void startWithTarget(Node *target) override; /** - * @param time in seconds. + * @param time In seconds. */ virtual void update(float time) override; @@ -202,19 +235,23 @@ protected: Vec2 _accumulatedDiff; }; -/** Cardinal Spline path. - http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Cardinal_spline - @ingroup Actions +/** @class CardinalSplineBy + * Cardinal Spline path. + * http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Cardinal_spline + * @ingroup Actions */ class CC_DLL CardinalSplineBy : public CardinalSplineTo { public: - /** creates an action with a Cardinal Spline array of points and tension + /** Creates an action with a Cardinal Spline array of points and tension. * @code - * 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) + * 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). + * @param duration In seconds. + * @param point An PointArray. + * @param tension Goodness of fit. * @endcode */ static CardinalSplineBy* create(float duration, PointArray* points, float tension); @@ -231,28 +268,32 @@ protected: Vec2 _startPosition; }; -/** An action that moves the target with a CatmullRom curve to a destination point. - A Catmull Rom is a Cardinal Spline with a tension of 0.5. - http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull.E2.80.93Rom_spline - @ingroup Actions +/** @class CatmullRomTo + * An action that moves the target with a CatmullRom curve to a destination point. + * A Catmull Rom is a Cardinal Spline with a tension of 0.5. + * http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull.E2.80.93Rom_spline + * @ingroup Actions */ class CC_DLL CatmullRomTo : public CardinalSplineTo { public: - /** creates an action with a Cardinal Spline array of points and tension - * @param dt in seconds + /** Creates an action with a Cardinal Spline array of points and tension. + * @param dt In seconds. + * @param points An PointArray. * @code - * when this function bound to js or lua,the input params are changed - * in js: var create(var dt,var table) - * in lua: lcaol create(local dt, local table) + * When this function bound to js or lua,the input params are changed. + * In js: var create(var dt,var table). + * In lua: lcaol create(local dt, local table). * @endcode */ static CatmullRomTo* create(float dt, PointArray* points); /** - * initializes the action with a duration and an array of points - * @param dt in seconds + * Initializes the action with a duration and an array of points. + * + * @param dt In seconds. + * @param points An PointArray. */ bool initWithDuration(float dt, PointArray* points); @@ -261,25 +302,31 @@ public: virtual CatmullRomTo *reverse() const override; }; -/** An action that moves the target with a CatmullRom curve by a certain distance. - A Catmull Rom is a Cardinal Spline with a tension of 0.5. - http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull.E2.80.93Rom_spline - @ingroup Actions +/** @class CatmullRomBy + * An action that moves the target with a CatmullRom curve by a certain distance. + * A Catmull Rom is a Cardinal Spline with a tension of 0.5. + * http://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull.E2.80.93Rom_spline + * @ingroup Actions */ class CC_DLL CatmullRomBy : public CardinalSplineBy { public: - /** creates an action with a Cardinal Spline array of points and tension - * @param dt in seconds + /** Creates an action with a Cardinal Spline array of points and tension. + * @param dt In seconds. + * @param points An PointArray. * @code - * when this function bound to js or lua,the input params are changed - * in js: var create(var dt,var table) - * in lua: lcaol create(local dt, local table) + * When this function bound to js or lua,the input params are changed. + * In js: var create(var dt,var table). + * In lua: lcaol create(local dt, local table). * @endcode */ static CatmullRomBy* create(float dt, PointArray* points); - /** initializes the action with a duration and an array of points */ + /** Initializes the action with a duration and an array of points. + * + * @param dt In seconds. + * @param points An PointArray. + */ bool initWithDuration(float dt, PointArray* points); // Override diff --git a/cocos/2d/CCAnimation.h b/cocos/2d/CCAnimation.h index 5b7027fe9a..e51659de17 100644 --- a/cocos/2d/CCAnimation.h +++ b/cocos/2d/CCAnimation.h @@ -46,17 +46,20 @@ class SpriteFrame; */ /** AnimationFrame - A frame of the animation. It contains information like: - - sprite frame name - - # of delay units. - - offset + * + * A frame of the animation. It contains information like: + * - sprite frame name. + * - # of delay units. + * - offset @since v2.0 */ class CC_DLL AnimationFrame : public Ref, public Clonable { public: - + /** @struct DisplayedEventInfo + * When the animation display,Dispatches the event of UserData. + */ struct DisplayedEventInfo { Node* target; @@ -64,13 +67,23 @@ public: }; /** - * Creates the animation frame with a spriteframe, number of delay units and a notification user info + * Creates the animation frame with a spriteframe, number of delay units and a notification user info. + * + * @param spriteFrame The animation frame with a spriteframe. + * @param delayUnits Number of delay units. + * @param userInfo A notification user info. * @since 3.0 */ static AnimationFrame* create(SpriteFrame* spriteFrame, float delayUnits, const ValueMap& userInfo); - + /** Return a SpriteFrameName to be used. + * + * @return a SpriteFrameName to be used. + */ SpriteFrame* getSpriteFrame() const { return _spriteFrame; }; - + /** Set the SpriteFrame. + * + * @param frame A SpriteFrame will be used. + */ void setSpriteFrame(SpriteFrame* frame) { CC_SAFE_RETAIN(frame); @@ -78,19 +91,30 @@ public: _spriteFrame = frame; } - /** Gets the units of time the frame takes */ + /** Gets the units of time the frame takes. + * + * @return The units of time the frame takes. + */ float getDelayUnits() const { return _delayUnits; }; - /** Sets the units of time the frame takes */ + /** Sets the units of time the frame takes. + * + * @param delayUnits The units of time the frame takes. + */ void setDelayUnits(float delayUnits) { _delayUnits = delayUnits; }; /** @brief Gets user infomation - A AnimationFrameDisplayedNotification notification will be broadcast when the frame is displayed with this dictionary as UserInfo. If UserInfo is nil, then no notification will be broadcast. + * A AnimationFrameDisplayedNotification notification will be broadcast when the frame is displayed with this dictionary as UserInfo. + * If UserInfo is nil, then no notification will be broadcast. + * + * @return A dictionary as UserInfo */ const ValueMap& getUserInfo() const { return _userInfo; }; ValueMap& getUserInfo() { return _userInfo; }; - /** Sets user infomation */ + /** Sets user infomation. + * @param A dictionary as UserInfo. + */ void setUserInfo(const ValueMap& userInfo) { _userInfo = userInfo; @@ -131,89 +155,127 @@ private: -/** A Animation object is used to perform animations on the Sprite objects. - -The Animation object contains AnimationFrame objects, and a possible delay between the frames. -You can animate a Animation object by using the Animate action. Example: - -@code - sprite->runAction(Animate::create(animation)); -@endcode - +/** @class Animation + * A Animation object is used to perform animations on the Sprite objects. + * The Animation object contains AnimationFrame objects, and a possible delay between the frames. + * You can animate a Animation object by using the Animate action. Example: + * @code + * sprite->runAction(Animate::create(animation)); + * @endcode */ class CC_DLL Animation : public Ref, public Clonable { public: - /** Creates an animation - @since v0.99.5 + /** Creates an animation. + * @since v0.99.5 */ static Animation* create(void); /* Creates an animation with an array of SpriteFrame and a delay between frames in seconds. - The frames will be added with one "delay unit". - @since v0.99.5 + * The frames will be added with one "delay unit". + * @since v0.99.5 + * @param arrayOfSpriteFrameNames An array of SpriteFrame. + * @param delay A delay between frames in seconds. + * @param loops The times the animation is going to loop. */ static Animation* createWithSpriteFrames(const Vector& arrayOfSpriteFrameNames, float delay = 0.0f, unsigned int loops = 1); /* Creates an animation with an array of AnimationFrame, the delay per units in seconds and and how many times it should be executed. - @since v2.0 + * @since v2.0 * @js NA + * @param arrayOfAnimationFrameNames An animation with an array of AnimationFrame. + * @param delayPerUnit The delay per units in seconds and and how many times it should be executed. + * @param loops The times the animation is going to loop. */ static Animation* create(const Vector& arrayOfAnimationFrameNames, float delayPerUnit, unsigned int loops = 1); /** Adds a SpriteFrame to a Animation. - The frame will be added with one "delay unit". + * + * @param frame The frame will be added with one "delay unit". */ void addSpriteFrame(SpriteFrame *frame); /** Adds a frame with an image filename. Internally it will create a SpriteFrame and it will add it. - The frame will be added with one "delay unit". - Added to facilitate the migration from v0.8 to v0.9. + * The frame will be added with one "delay unit". + * Added to facilitate the migration from v0.8 to v0.9. + * @param filename The path of SpriteFrame. */ void addSpriteFrameWithFile(const std::string& filename); /** - @deprecated. Use addSpriteFrameWithFile() instead + * @deprecated. Use addSpriteFrameWithFile() instead. */ CC_DEPRECATED_ATTRIBUTE void addSpriteFrameWithFileName(const std::string& filename){ addSpriteFrameWithFile(filename);} /** Adds a frame with a texture and a rect. Internally it will create a SpriteFrame and it will add it. - The frame will be added with one "delay unit". - Added to facilitate the migration from v0.8 to v0.9. + * The frame will be added with one "delay unit". + * Added to facilitate the migration from v0.8 to v0.9. + * @param pobTexture A frame with a texture. + * @param rect The Texture of rect. */ void addSpriteFrameWithTexture(Texture2D* pobTexture, const Rect& rect); - /** Gets the total Delay units of the Animation. */ + /** Gets the total Delay units of the Animation. + * + * @return The total Delay units of the Animation. + */ float getTotalDelayUnits() const { return _totalDelayUnits; }; - /** Sets the delay in seconds of the "delay unit" */ + /** Sets the delay in seconds of the "delay unit". + * + * @param setDelayPerUnit The delay in seconds of the "delay unit". + */ void setDelayPerUnit(float delayPerUnit) { _delayPerUnit = delayPerUnit; }; - /** Gets the delay in seconds of the "delay unit" */ + /** Gets the delay in seconds of the "delay unit". + * + * @return The delay in seconds of the "delay unit". + */ float getDelayPerUnit() const { return _delayPerUnit; }; - /** Gets the duration in seconds of the whole animation. It is the result of totalDelayUnits * delayPerUnit */ + /** Gets the duration in seconds of the whole animation. It is the result of totalDelayUnits * delayPerUnit. + * + * @return Result of totalDelayUnits * delayPerUnit. + */ float getDuration() const; - /** Gets the array of AnimationFrames */ + /** Gets the array of AnimationFrames. + * + * @return The array of AnimationFrames. + */ const Vector& getFrames() const { return _frames; }; - /** Sets the array of AnimationFrames */ + /** Sets the array of AnimationFrames. + * + * @param frames The array of AnimationFrames. + */ void setFrames(const Vector& frames) { _frames = frames; } - /** Checks whether to restore the original frame when animation finishes. */ + /** Checks whether to restore the original frame when animation finishes. + * + * @return Restore the original frame when animation finishes. + */ bool getRestoreOriginalFrame() const { return _restoreOriginalFrame; }; - /** Sets whether to restore the original frame when animation finishes */ + /** Sets whether to restore the original frame when animation finishes. + * + * @param restoreOriginalFrame Whether to restore the original frame when animation finishes. + */ void setRestoreOriginalFrame(bool restoreOriginalFrame) { _restoreOriginalFrame = restoreOriginalFrame; }; - /** Gets the times the animation is going to loop. 0 means animation is not animated. 1, animation is executed one time, ... */ + /** Gets the times the animation is going to loop. 0 means animation is not animated. 1, animation is executed one time, ... + * + * @return The times the animation is going to loop. + */ unsigned int getLoops() const { return _loops; }; - /** Sets the times the animation is going to loop. 0 means animation is not animated. 1, animation is executed one time, ... */ + /** Sets the times the animation is going to loop. 0 means animation is not animated. 1, animation is executed one time, ... + * + * @param loops The times the animation is going to loop. + */ void setLoops(unsigned int loops) { _loops = loops; }; // overrides @@ -223,16 +285,16 @@ CC_CONSTRUCTOR_ACCESS: Animation(); virtual ~Animation(void); - /** Initializes a Animation */ + /** Initializes a Animation. */ bool init(); - /** Initializes a Animation with frames and a delay between frames - @since v0.99.5 + /** Initializes a Animation with frames and a delay between frames. + * @since v0.99.5 */ bool initWithSpriteFrames(const Vector& arrayOfSpriteFrameNames, float delay = 0.0f, unsigned int loops = 1); - /** Initializes a Animation with AnimationFrame - @since v2.0 + /** Initializes a Animation with AnimationFrame. + * @since v2.0 */ bool initWithAnimationFrames(const Vector& arrayOfAnimationFrameNames, float delayPerUnit, unsigned int loops); @@ -240,16 +302,16 @@ protected: /** total Delay units of the Animation. */ float _totalDelayUnits; - /** Delay in seconds of the "delay unit" */ + /** Delay in seconds of the "delay unit". */ float _delayPerUnit; - /** duration in seconds of the whole animation. It is the result of totalDelayUnits * delayPerUnit */ + /** duration in seconds of the whole animation. It is the result of totalDelayUnits * delayPerUnit. */ float _duration; - /** array of AnimationFrames */ + /** array of AnimationFrames. */ Vector _frames; - /** whether or not it shall restore the original frame when the animation finishes */ + /** whether or not it shall restore the original frame when the animation finishes. */ bool _restoreOriginalFrame; /** how many times the animation is going to loop. 0 means animation is not animated. 1, animation is executed one time, ... */ diff --git a/cocos/2d/CCAnimationCache.h b/cocos/2d/CCAnimationCache.h index 1a8aba4c87..bf87979c51 100644 --- a/cocos/2d/CCAnimationCache.h +++ b/cocos/2d/CCAnimationCache.h @@ -36,6 +36,7 @@ THE SOFTWARE. NS_CC_BEGIN + class Animation; /** @@ -44,12 +45,10 @@ class Animation; */ /** Singleton that manages the Animations. -It saves in a cache the animations. You should use this class if you want to save your animations in a cache. - -Before v0.99.5, the recommend way was to save them on the Sprite. Since v0.99.5, you should use this class instead. - -@since v0.99.5 -*/ + * It saves in a cache the animations. You should use this class if you want to save your animations in a cache. + * Before v0.99.5, the recommend way was to save them on the Sprite. Since v0.99.5, you should use this class instead. + * @since v0.99.5 + */ class CC_DLL AnimationCache : public Ref { public: @@ -62,27 +61,33 @@ public: * @lua NA */ ~AnimationCache(); - /** Returns the shared instance of the Animation cache */ + /** Returns the shared instance of the Animation cache. + * + * @return The shared instance of the Animation cache. + */ static AnimationCache* getInstance(); - /** Purges the cache. It releases all the Animation objects and the shared instance. - */ + /** Purges the cache. It releases all the Animation objects and the shared instance. */ static void destroyInstance(); - /** @deprecated Use getInstance() instead */ + /** @deprecated Use getInstance() instead. */ CC_DEPRECATED_ATTRIBUTE static AnimationCache* sharedAnimationCache() { return AnimationCache::getInstance(); } - /** @deprecated Use destroyInstance() instead */ + /** @deprecated Use destroyInstance() instead. */ CC_DEPRECATED_ATTRIBUTE static void purgeSharedAnimationCache() { return AnimationCache::destroyInstance(); } bool init(void); /** Adds a Animation with a name. - */ + * + * @param animation An animation. + * @param name The name of animation. + */ void addAnimation(Animation *animation, const std::string& name); /** Deletes a Animation from the cache. - + * + * @param name The name of animation. */ void removeAnimation(const std::string& name); /** @deprecated. Use removeAnimation() instead @@ -92,29 +97,33 @@ public: CC_DEPRECATED_ATTRIBUTE void removeAnimationByName(const std::string& name){ removeAnimation(name);} /** Returns a Animation that was previously added. - If the name is not found it will return nil. - You should retain the returned copy if you are going to use it. - */ + * If the name is not found it will return nil. + * You should retain the returned copy if you are going to use it. + * + * @return A Animation that was previously added. If the name is not found it will return nil. + */ Animation* getAnimation(const std::string& name); /** - @deprecated. Use getAnimation() instead + * @deprecated. Use getAnimation() instead * @js NA * @lua NA */ CC_DEPRECATED_ATTRIBUTE Animation* animationByName(const std::string& name){ return getAnimation(name); } - /** Adds an animation from an NSDictionary - Make sure that the frames were previously loaded in the SpriteFrameCache. - @param plist The path of the relative file,it use to find the plist path for load SpriteFrames. - @since v1.1 + /** Adds an animation from an NSDictionary. + * Make sure that the frames were previously loaded in the SpriteFrameCache. + * @param an NSDictionary. + * @param plist The path of the relative file,it use to find the plist path for load SpriteFrames. + * @since v1.1 */ void addAnimationsWithDictionary(const ValueMap& dictionary,const std::string& plist); /** Adds an animation from a plist file. - Make sure that the frames were previously loaded in the SpriteFrameCache. - @since v1.1 + * Make sure that the frames were previously loaded in the SpriteFrameCache. + * @since v1.1 * @js addAnimations * @lua addAnimations + * @param An animation from a plist file. */ void addAnimationsWithFile(const std::string& plist); diff --git a/cocos/2d/CCAtlasNode.h b/cocos/2d/CCAtlasNode.h index 5162a69b18..2f53918dde 100644 --- a/cocos/2d/CCAtlasNode.h +++ b/cocos/2d/CCAtlasNode.h @@ -42,26 +42,36 @@ NS_CC_BEGIN class TextureAtlas; -/** @brief AtlasNode is a subclass of Node that implements the RGBAProtocol and TextureProtocol protocol - -It knows how to render a TextureAtlas object. -If you are going to render a TextureAtlas consider subclassing AtlasNode (or a subclass of AtlasNode) - -All features from Node are valid, plus the following features: -- opacity and RGB colors -*/ +/** @brief AtlasNode is a subclass of Node that implements the RGBAProtocol and TextureProtocol protocol. + * It knows how to render a TextureAtlas object. + * If you are going to render a TextureAtlas consider subclassing AtlasNode (or a subclass of AtlasNode). + * All features from Node are valid, plus the following features: + * - opacity and RGB colors. + */ class CC_DLL AtlasNode : public Node, public TextureProtocol { public: - /** creates a AtlasNode with an Atlas file the width and height of each item and the quantity of items to render*/ + /** creates a AtlasNode with an Atlas file the width and height of each item and the quantity of items to render. + * + * @param filename The path of Atlas file. + * @param tileWidth The width of the item. + * @param tileHeight The height of the item. + * @param itemsToRender The quantity of items to render. + */ static AtlasNode * create(const std::string& filename, int tileWidth, int tileHeight, int itemsToRender); /** updates the Atlas (indexed vertex array). - * Shall be overridden in subclasses + * Shall be overridden in subclasses. */ virtual void updateAtlasValues(); - + + /** Set an buffer manager of the texture vertex. */ void setTextureAtlas(TextureAtlas* textureAtlas); + + /** Return the buffer manager of the texture vertex. + * + * @return Return A TextureAtlas. + */ TextureAtlas* getTextureAtlas() const; void setQuadsToDraw(ssize_t quadsToDraw); @@ -95,10 +105,10 @@ CC_CONSTRUCTOR_ACCESS: AtlasNode(); virtual ~AtlasNode(); - /** initializes an AtlasNode with an Atlas file the width and height of each item and the quantity of items to render*/ + /** Initializes an AtlasNode with an Atlas file the width and height of each item and the quantity of items to render*/ bool initWithTileFile(const std::string& tile, int tileWidth, int tileHeight, int itemsToRender); - /** initializes an AtlasNode with a texture the width and height of each item measured in points and the quantity of items to render*/ + /** Initializes an AtlasNode with a texture the width and height of each item measured in points and the quantity of items to render*/ bool initWithTexture(Texture2D* texture, int tileWidth, int tileHeight, int itemsToRender); protected: @@ -109,30 +119,30 @@ protected: friend class Director; void setIgnoreContentScaleFactor(bool bIgnoreContentScaleFactor); - //! chars per row + /** Chars per row. */ int _itemsPerRow; - //! chars per column + /** Chars per column. */ int _itemsPerColumn; - //! width of each char + /** Width of each char. */ int _itemWidth; - //! height of each char + /** Height of each char. */ int _itemHeight; Color3B _colorUnmodified; TextureAtlas* _textureAtlas; - // protocol variables + /** Protocol variables. */ bool _isOpacityModifyRGB; BlendFunc _blendFunc; - // quads to draw + /** Quads to draw. */ ssize_t _quadsToDraw; - // color uniform + /** Color uniform. */ GLint _uniformColor; - // This varible is only used for LabelAtlas FPS display. So plz don't modify its value. + /** This varible is only used for LabelAtlas FPS display. So plz don't modify its value. */ bool _ignoreContentScaleFactor; - // quad command + /** Quad command. */ QuadCommand _quadCommand; private: From 431b3593a7271ac33a2d0808858b27a03fd0a410 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 20:12:34 +0800 Subject: [PATCH 30/32] [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 31944da08c43249a9e179a2c8b0bc79440cc6c98 Mon Sep 17 00:00:00 2001 From: SuYaohui <365886954@qq.com> Date: Wed, 18 Mar 2015 20:26:16 +0800 Subject: [PATCH 31/32] [ci skip]Action,ActionCamera,ActionCatmullRom,Animation,AnimationCache,AtlasNode --- cocos/2d/CCAnimation.h | 2 +- cocos/2d/CCAnimationCache.h | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/cocos/2d/CCAnimation.h b/cocos/2d/CCAnimation.h index e51659de17..5d066cb60d 100644 --- a/cocos/2d/CCAnimation.h +++ b/cocos/2d/CCAnimation.h @@ -113,7 +113,7 @@ public: ValueMap& getUserInfo() { return _userInfo; }; /** Sets user infomation. - * @param A dictionary as UserInfo. + * @param userInfo A dictionary as UserInfo. */ void setUserInfo(const ValueMap& userInfo) { diff --git a/cocos/2d/CCAnimationCache.h b/cocos/2d/CCAnimationCache.h index bf87979c51..8f69c37a92 100644 --- a/cocos/2d/CCAnimationCache.h +++ b/cocos/2d/CCAnimationCache.h @@ -112,7 +112,7 @@ public: /** Adds an animation from an NSDictionary. * Make sure that the frames were previously loaded in the SpriteFrameCache. - * @param an NSDictionary. + * @param dictionary An NSDictionary. * @param plist The path of the relative file,it use to find the plist path for load SpriteFrames. * @since v1.1 */ @@ -123,7 +123,7 @@ public: * @since v1.1 * @js addAnimations * @lua addAnimations - * @param An animation from a plist file. + * @param plist An animation from a plist file. */ void addAnimationsWithFile(const std::string& plist); From 19fc6a1495fb6b82d6102e4e0d2f0d0aa3476a83 Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 18 Mar 2015 20:37:43 +0800 Subject: [PATCH 32/32] 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) {