【cocos2d-x官方文档】 从v1.x到2.x的API更改

来源:互联网 发布:淘宝卖袜子的店铺 编辑:程序博客网 时间:2024/05/10 08:54

本文由 sharyu 翻译,转载请注明原出处!!

从v1.x到2.x的API变化
1. 新的API概念
1.1 静态构造函数
1.2 单例
1.3 事件回调
2. 数据结构:CCDictionary和CCArray
2.1 为什么CCMutableDictionary被移除了?
2.2 CCDictionary的主键类型
2.3 如何使用CCDictionary?
2.4 为什么CCMutableArray被移除了?
3. 用Classname::isStatus的方式来返回bool值
4. 类
Director类
CCActionManager,CCTouchDispatcher,CCScheduler类
Sprite类
SpriteBatchNode类
CCGeometry,CCPoint,CCSize,CCRect类
CCTouch类
Transitions类
Particle System类
Menu类
Animate类
MotionStreak类
Layer类
Animation类
ProgressTimer类
CCNode类
RenderTexture类
CCFileUtils类
CCString类

1.新的API概念
根据 Cocos2d Javascript API,我们将大多数API的更改适用到了C++。下面罗列了这些更改的基本概念。
1.1 静态构造函数
[v2.0] 用Classname::create替代Classname::ClassnameWithResource。请参考About Static Constructor API changes in cocos2d-x v2.0。Lua API集合和Javascript API集合也使用了这种清晰的结构。
[v2.0] 使用createWithResource来避免冲突
[v2.0] 从::create()方法返回的CCObject*对象总是自动释放(auto-release)的。
1.2 单例
[v2.0.1] 所有单例都包含一个静态构造方法Singleton::getInstance(),和一个析构方法Singleton::destroyInstance(),替换了原来的@Classname::sharedClassname。这个变化同样适用于lua和javascript绑定。
1.3 事件回调
[v2.0.1] 事件回调, 例如:CCTouchDelegate::ccTouchesBegan/Moved/Ended/Cancelled(), 被重命名为CCSomethingDelegate::onSomethingDone(),包括:
Standard touch delegate: onTouchesBegan/Moved/Ended/Cancelled
Targeted touch delegate: onTouchBegan/Moved/Ended/Cancelled
Keypad delegate: onKeyBackClicked, onKeyMenuClicked
G-Sensor delegate: onAccelerometerChanged
2.数据结构:CCDictionary和CCArray
2.1 为什么CCMutableDictionary被取消了? 

在gles20分支里, ‘CCMutableDictionary’ and ‘CCMutableArray’被取消了。你需要用 CCDictionary and CCArray来替换它们。
CCDictionary是用UTHash来实现的。 CCMutableDictionary是用stl实现的, 相比较而言 CCDictionary的效率会至少提高两倍。并且, CCDictionary没有使用cpp的模版,因此可以方便地绑定到脚本。
2.2 CCDictionary中主键支持的类型
目前, CCDictionary的主键支持两种类型: ‘std::stirng’和’int’。一个 CCDictionary实例只支持一种主键类型。
在你第一次调用 ‘setObject’的时候,主键类型会被确认下来。
2.3 如何使用CCDictionary?
CCDictionary和 CCMutableDictionary的用法基本相同。我们保留了相同的API,移除了遍历字典时用到的 ‘begin’,’end’和’next’方法。取而代之,我们使用了 CCDICT_FOREACH宏。使用 CCDICT_FOREACH的方法和 CCARRAY_FOREACH的用法极为相似。
下面的代码阐述了如何遍历 CCDictionary:

  1. CCMutableDictionary    CCDictionary
  2. std::vector keys = theDict->allKeys();  CCDictElement* pElement = NULL;
  3. std::vector::iterator it;       CCDICT_FOREACH(theDict, pElement)
  4. for (it = keys.begin(); it != keys.end(); it++)
  5. {
  6. CCObjectSubClass* pSubClassObj = (CCObjectSubClass*)pElement->getObject();
  7. std::string oneKey = *it;    // You can also get the current key, but make sure you know the key type.
  8. CCObjectSubClass* pSubClassObj = theDict->objectForKey(oneKey);   std::string oneStrKey = pElement->getStrKey(); // if the key type is string.
  9. // do some operation by using pSubClass pointer.      
  10. // int oneIntKey = pElement->getIntKey(); // if the key type is integer.
  11. // do some operation by using pSubClass pointer.
  12. }

我们保留了 CCDictionary::allKeys方法,这样就可以按照与 CCMutableDictionary同样的方法遍历字典,但是我们强烈不建议这么做。因为 CCDICT_FOREACH的性能比获取所有主键然后使用 CCARRAY_FOREACH来遍历高的多。
如果你希望在lua中遍历 CCDictionary,当然,你无法使用 CCDICT_FOREACH宏,在这种情况下,你只能使用旧的方法。
2.4 为什么CCMutableArray被取消了?
在cocos2d-x 1.0.1中,我们有 CCArray和 CCMutableArray,让用户十分困惑,同时, CCMutableArray使用了模版和stl,坏处和 CCMutableDictionary一样。旧的CCArray不支持反向遍历数组,现在我们提供了 CCARRAY_FOREACH_REVERSE宏来实现此功能。
3.使用Classname::isStatus方式来返回一个bool类型
对于bool类型:
getter方法从getIsBool()或者getBool()统一为isBool()。
setter方法从setIsBool(value)统一为setBool(value)。
所有使用频繁的方法都被加粗标记了。

function name before  function name in v2.x  CCCamera::getDirtyCCCamera::isDirtyCCConfiguration::isSupportsNPOTCCConfiguration::supportsNPOTCCConfiguration::isSupportsPVRTCCCConfiguration::supportsPVRTCCCConfiguration::isSupportsBGRA8888CCConfiguration::supportsBGRA8888CCConfiguration::isSupportsDiscardFramebufferCCConfiguration::supportsDiscardFramebufferCCConfiguration::isSupportsShareableVAOCCConfiguration::supportsShareableAVOCCNode::getIsVisibleCCNode::isVisibleCCNode::setIsVisibleCCNode::setVisibleCCNode::getIsRunningCCNode::isRunningCCGridBase::setIsTextureFlippedCCGridBase::setTextureFlippedCCRGBAProtocol::getIsOpacityModifyRGBCCRGBAProtocol::isOpacityModifyRGBCCRGBAProtocol::setIsOpacityModifyRGBCCRGBAProtocol::setOpacityModifyRGBCCLayer::getIsTouchEnabledCCLayer::isTouchEnabledCCLayer::setIsTouchEnabledCCLayer::setTouchEnabledCCMenu::getIsEnabledCCMenu::isEnabledCCMenu::setIsEnabledCCMenu::setEnabledCCParticleSystem::getIsActiveCCParticle::isActiveCCParticleSystem::getIsAutoRemovedOnFinishCCParticle::isAutoRemovedOnFinishCCParticleSystem::setIsAutoRemovedOnFinishCCParticle::setAutoRemovedOnFinishCCParticleSystem::getIsBlendActiveCCParticleSystem::isBlendActiveCCParticleSystem::setIsBlendActiveCCParticleSystem::setBlendActiveCCTexture2D::getIsHasPremultipliedAlphaCCTexture2D::hasPremultipliedAlphaCCFileUtils::setIsPopupNotifyCCFileUtils::isPopupNotifyCCFileUtils::setIsPopupNotifyCCFileUtils::setPopupNotifyCCScriptSupport::getIsMultiTouchesCCScriptSupport::isMultiTouchesCCScriptSupport::setIsVisibleCCScriptSupport::setVisible

4.类
Director类

[v2.0-sync] CCDirector::setDisplayFPS(bool) -> setDisplayStats(bool)。现在左下的状态显示3个数字:
最上面的数字显示每帧调用了多少次OpenGL的draw方法。
中间的数字表示每帧耗费多少秒(SPF)。
最下面的数字是我们都很熟悉的FPS。
[v2.0-sync] CCDirector::isRetinaDisplay()被移除了。
[v2.0] *在Resources/下添加fps_images.png,并且添加到工程设置中。现在CCDirector使用CCLabelAtlas来显示FPS,这样做可以提高在android上的运行效率。
CCActionManager, CCTouchDispatcher, CCScheduler类
[v2.0-sync] CCActionManager, CCTouchDispatcher, CCScheduler现在是CCDirector的成员变量。但包含’cache’的单例类,比如CCTextureCache, CCAnimationCache, CCShaderCache还维持原状。
Sprite类
[v2.0-sync] CCSprite::displayedFrame() -> displayFrame()
SpriteBatchNode类
[v2.0-sync] CCSprite::spriteWithBatchNode(…)被移除,请使用: sprite = CCSprite::spriteWithTexture(batchNode->getTexture(), CCRect*); batchNode->addChild(sprite);代替。
[v2.0-sync] CCSprite::initWithBatchNode(…), initWithBatchNodeInPixels(…) 被移除,请使用CCSprite::setBatchNode(…)代替。
[v2.0-sync] bool CCSprite::isUsesBatchNode()被移除,请使用CCSpriteBatchNode* getSpriteBatchNode(),要判断返回值是否为NULL。
使用batch node创建sprite的示例代码:

  1. // create batch node from image file
  2. CCSpriteBatchNode* batch = CCSpriteBatchNode::create("BatchNodeTexture.png");
  3. // get the texture in batch node
  4. CCTexture2D* texture = batch->getTexture();
  5. // create sprite from this texture
  6. CCSprite* sprite = CCSprite::createWithTexture(texture, CCRectMake(0,0,32,32));
  7. // organize the child relation
  8. layer->addChild(batch);
  9. batch->addChild(sprite);

CCGeometry, CCPoint, CCSize, CCRect类
使用面向对象的方法替代静态函数
v2.0.2] 使用p1.equals(p2)代替CCPoint::CCPointEqualToPoint(p1, p2)
[v2.0.2] 使用s1.equals(s2)代替CCSize::CCSizeEqualToSize(s1, s2)
[v2.0.2] 使用r.getMinX(), r.getMaxY()系列代替CCRect:CCRectGetMinX(r), CCRect::CCRectGetMaxY(r) 系列
[v2.0.2] 使用r1.equals(r2)代替CCRect::CCRectEqualsToRect(r1, r2)
[v2.0.2] 使用r1.contrainsPoint(p1)代替CCRect::CCRectContainsPoint(r1, p1)
[v2.0.2] 使用r1.intersectsRect(r2)代替CCRect::CCRectIntersectsRect(r1, r2)
CCTouch类
CCTouch中添加了一些方便的API
[v2.0.2] locationInView()重命名为getLocationInView()
[v2.0.2] previousLocationInView()重命名为CCTouch::getPreviousLocationInView()
[v2.0.2] 添加getLocation()方法,直接返回OpenGL坐标
[v2.0.2] 添加getPreviousLocation()方法,直接返回OpenGL坐标
[v2.0.2] 添加getDelta()方法,返回OpenGL坐标系中当前位置和上一位置间的变化量
变换
[v2.0-sync] CCTransitionRadialCW -> CCTransitionProgressRadialCW
[v2.0-sync] CCTransitionRadialCCW -> CCTransitionProgressRadialCCW
粒子系统
[v2.0-sync] ARCH_OPTIMAL_PARTICLE_SYSTEM -> CCParticleSystemQuad,
[v2.0-sync] CCParticleSystemQuad::initIndices() -> setupIndices()
[v2.0] CCParticleSystemPoint被移除,请使用CCParticleSystemQuad代替。
菜单
[v2.0] CCMenuItemImage::initFromNormalImage -> initWithNormalImage
Animate类
[v2.0-sync] CCAnimate::actionWithDuration(ccTime duration, CCAnimation *pAnimation, bool bRestoreOriginalFrame)被移除,用CCAnimation::setDelayPerUnit(float)代替。
MontionStreak类
[v2.0-sync] CCMotionStreak::streakWithFade和initWithFade改变了参数,请参考CCMotionStreak.h来获得更多细节。
Layer类
[v2.0] CCLayerColor::layerWithColorWidthHeight被重命名为layerWithColor
Animation类
[v2.0-sync] CCAnimation::setDelay(float) / getDelay()重命名为setDelayPerUnit(float)/getDelay()
[v2.0] CCAnimation::initWithFrames( CCMuatableArray<>* )重命名为initWithSpriteFrames(CCArray*)
[v2.0-sync] CCAnimation::addFrame(CCSpriteFrame*)重命名为addSpriteFrame(CCSpriteFrame*)
[v2.0-sync] CCAnimation::animationWithFrames重命名为animationWithSpriteFrames
[v2.0-sync] CCAnimation::addFrameWithFileName -> addSpriteFrameWithFileName
[v2.0-sync] CCAnimation::addFrameWithTexture -> addSpriteFrameWithTexture
ProgressTimer类
[v2.0-sync] CCProgressTimer::initWithFile(char*) and initWithTexture(CCTexture2D*) 被移除,用 initWithSprite(CCSprite*) 代替。
[v2.0-sync] CCProgressTimer::progressWithFile and progressWithTexture被移除,使用 progressWithSprite代替。
CCNode类
[v2.0-sync] CCNode::get/setPositionInPixels, get/setAnchorPointInPixels, get/setContentSizeInPixels, boundingBoxInPixels()被移除,替换为不带”InPixel”后缀的方法。
RenderTexture类
[v2.0] CCRenderTexture::saveBuffer(…)更改为saveToFile(…)
CCFileUtils类
[v2.0] CCFileUtils::dictionaryWithContentsOfFile被更改为 CCDictionary::createWithContentsOfFile, 添加CCArray::createWithContentsOfFile方法。
CCString类
1. 更多有用的方法。

  1. /** create a string with std string, you can also pass a c string pointer because the default constuctor of std::string can access a c string pointer.
  2. *  @return A CCString pointer which is an autorelease object pointer,
  3. *          it means that you needn't do a release operation unless you retain it.
  4. */
  5. static CCString* create(const std::string&amp; str);
  6.  
  7. /** create a string with format, it's similar with the c function 'sprintf', the default buffer size is (1024*100) bytes,
  8. *  if you want to change it, you should modify the kMaxStringLen macro in CCString.cpp file.
  9. *  @return A CCString pointer which is an autorelease object pointer,
  10. *          it means that you needn't do a release operation unless you retain it.
  11. */
  12. static CCString* createWithFormat(const char* format, ...);
  13.  
  14. /** create a string with binary data
  15. *  @return A CCString pointer which is an autorelease object pointer,
  16. *          it means that you needn't do a release operation unless you retain it.
  17. */
  18. static CCString* createWithData(unsigned char* pData, unsigned long nLen);
  19.  
  20. /** create a string with a file,
  21. *  @return A CCString pointer which is an autorelease object pointer,
  22. *          it means that you needn't do a release operation unless you retain it.
  23. */
  24. static CCString* createWithContentsOfFile(const char* pszFileName);

2. 一些接口的变化
toInt        —>  intValue
toUint       —>  uintValue
toDouble     —>  doubleValue
toFloat      —>  floatValue
toBool       —>  boolValue
toStdStirng(deprecated)
getCString(new api for getting c string)
3. 有用的宏

  1. #define CCStringMake(str) CCString::stringWithCString(str)
  2. #define ccs               CCStringMake

这些宏可以更容易地创建一个自动释放的CCString对象,比如,如果我们想创建许多CCString对象,并且将他们添加到CCArray中,下面代码会使你的代码更简洁。

  1. CCArray *stringArray = CCArray::arrayWithObjects(
  2. ccs("Hello"),
  3. ccs("Variable"),
  4. ccs("Size"),
  5. ccs("!"),
  6. NULL);