Cocos2d-x v2.0 Migration Guide¶
This guide will be updated every new cocos2d-x v2.0 released.
Summary¶
- contains some API changes
- contains some new features
- supports OpenGL ES 2.0, OpenGL ES 1.1 is no longer supported
- supports iOS, Android and win32
Changes the same as cocos2d-iphone v20¶
Cocos2d-X v20 ports from cocos2d-iphone v20, so it contains the changes that cocos2d-iphone v20 makes.
So you can refer migrate_to_v2.0 for these changes
- CCTransitionRadialCW is renamed to CCTransitionProgressRadialCW
- CCTransitionRadialCCW is renamed to CCTransitionProgressRadialCCW
- ARCH_OPTIMAL_PARTICLE_SYSTEM is should be replace to CCParticleSystemQuad,
- CCParticleSystemPoint is removed in gles20 branch
- CCMenuItemImage::initFromNormalImage is renamed to initWithNormalImage
- CCDirector::setDisplayFPS(bool) is renamed to setDisplayStats(bool)
- CCAnimate::initWithDuration(ccTime duration, CCAnimation *pAnimation, bool bRestoreOriginalFrame) method is removed, call CCAnimation::setDelayPerUnit(float) instead
- CCAnimate::actionWithDuration(ccTime duration, CCAnimation *pAnimation, bool bRestoreOriginalFrame) method is removed, call CCAnimation::setDelayPerUnit(float) instead
- CCMotionStreak::streakWithFade and initWithFade changed their params, please CCMotionStreak.h for details.
- CCLayerColor::layerWithColorWidthHeight is renamed to layerWithColor
- CCAnimation::setDelay(float) / getDelay() are renamed to setDelayPerUnit(float)/getDelay()
- CCAnimation::initWithFrames(
CCMuatableArray<>*) is renamed to initWithSpriteFrames(CCArray*) - CCAnimation::addFrame(CCSpriteFrame*) is renamed to addSpriteFrame(CCSpriteFrame*)
- CCAnimation::animationWithFrames is renamed to animationWithSpriteFrames
- CCAnimation::addFrameWithFileName -> addSpriteFrameWithFileName
- CCAnimation::addFrameWithTexture -> addSpriteFrameWithTexture
- CCProgressTimer::initWithFile(char*) and initWithTexture(CCTexture2D*) are removed, use initWithSprite(CCSprite*) instead.
- CCProgressTimer::progressWithFile and progressWithTexture are removed, use progressWithSprite instead
- CCNode::get/setPositionInPixels, get/setAnchorPointInPixels, get/setContentSizeInPixels, boundingBoxInPixels(), are remove, use the properties without "InPixel" instead
- CCParticleSystemQuad::initIndices() is renamed to setupIndices()
- CCDirector::isRetinaDisplay() is removed
- CCRednerTexture::saveBuffer(...) is modified to saveToFile(...)
- bool CCSprite::isUsesBatchNode() is removed, please use CCSpriteBatchNode* getSpriteBatchNode() instead, judge if the return value is NULL
- important CCSprite::spriteWithBatchNode(...) is removed, please use:
sprite = CCSprite::spriteWithTexture(batchNode->getTexture(), CCRect*); batchNode->addChild(sprite);instead - CCSprite::initWithBatchNode(...), initWithBatchNodeInPixels(...) are removed, use CCSprite::setBatchNode(...) instead
- CCSprite::displayedFrame() is renamed to displayFrame()
Cocos2d-x specific changes¶
Following are changes Cocos2d-X specific.
CCDictionary and CCArray¶
1. Why CCMutableDictionary is Deprecated?
In gles20 branch, 'CCMutableDictionary' and 'CCMutableArray' are deprecated. You should use CCDictionary and CCArray instead.
CCDictionary is implemented by UTHash. Compared with the old CCMutableDictionary which is implemented by stl, the efficiency of the CCDictionary
is increased by at least two times. Also, CCDictionary now does not use template of cpp, so it can easily be bound to script.2. Key Type?
Currently, CCDictionary supports two kinds of key type, which are 'std::stirng' and 'int'. One CCDictionary instance only supports one unique key type.
It is confirmed once you first invoke 'setObject'.3. How to Use CCDictionary?
The way of using CCDictionary is almost the same as CCMutableDictionary. We kept the same api and removed the 'begin', 'end' and 'next' method which are used in
iterating the whole dictionary. Instead, we use CCDICT_FOREACH macro to achieve that. The way of using CCDICT_FOREACH is quite the same as CCARRAY_FOREACH.
The following will illustrate how to iterate CCDictionary :
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
CCMutableDictionary<std::string, CCObjectSubClass*> | CCDictionary
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
std::vector<std::string> keys = theDict->allKeys(); | CCDictElement* pElement = NULL;
std::vector<std::string>::iterator it; | CCDICT_FOREACH(theDict, pElement)
for (it = keys.begin(); it != keys.end(); it++) | {
{ | CCObjectSubClass* pSubClassObj = (CCObjectSubClass*)pElement->getObject();
std::string oneKey = *it; | // You can also get the current key, but make sure you know the key type.
CCObjectSubClass* pSubClassObj = theDict->objectForKey(oneKey); | std::string oneStrKey = pElement->getStrKey(); // if the key type is string.
// do some operation by using pSubClass pointer. | // int oneIntKey = pElement->getIntKey(); // if the key type is integer.
... | // do some operation by using pSubClass pointer.
... | ...
} | }
|
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
We kept CCDictionary::allKeys method, so you can also use the same way as CCMutableDictionary to iterate dictionary, but we strongly don't advise you to do that.
Becasue the performance of CCDICT_FOREACH is much higher than getting all key and then using CCARRAY_FOREACH to traverse dictionary.If you want to iterate CCDictionary at lua codes, of course, you can't use the CCDICT_FOREACH macro, in this case, you should use the old way to make it works.
4. Why CCMutableArray is deprecated?
In cocos2d-x 1.0.1, we have CCArray and CCMutableArray, which make users very confused,
and CCMutableArray also uses template and stl, the disadvantage is the same as CCMutableDictionary.
The old CCArray does not support reversely iterate array, we have provided the macro -- CCARRAY_FOREACH_REVERSE to achieve that.5. Moved CCFileUtils::dictionaryWithContentsOfFile to CCDictionary::dictionaryWithContentsOfFile, added CCArray::arrayWithContentsOfFile method.
CCControlExtension¶
CCControlExtension in Cocos2D-X was converted to C++ by Angus C, the usage is just the same as the obj-c version. If you want to know more details, you should visit its homepage http://yannickloriot.com/2011/08/create-a-control-object-with-cocos2d-for-iphone/ .
Touch event¶
We have added a new method named 'getID' for CCTouch.
The id of CCTouch is used in MutiTouch situation, it identifies the unique name of your fingers on the screen.
You should visit MultiTouchTest in tests project for more details.
Supporting CocosBuilder¶
Cocos2d-X supports CocosBuilder on gles20 branch.
CCString (Added more useful methods in gles20 branch)¶
CCString is improved in gles20 branch
1. More Useful Methods.
/* static funcitons */
/** create a string with c string
* @return A CCString pointer which is an autorelease object pointer,
* it means that you needn't do a release operation unless you retain it.
*/
static CCString* stringWithCString(const char* pStr);
/** create a string with format, it's similar with the c function 'sprintf', the default buffer size is (1024*100) bytes,
* if you want to change it, you should modify the kMaxStringLen macro in CCString.cpp file.
* @return A CCString pointer which is an autorelease object pointer,
* it means that you needn't do a release operation unless you retain it.
*/
static CCString* stringWithFormat(const char* format, ...);
/** create a string with binary data
* @return A CCString pointer which is an autorelease object pointer,
* it means that you needn't do a release operation unless you retain it.
*/
static CCString* stringWithData(unsigned char* pData, unsigned long nLen);
/** create a string with a file,
* @return A CCString pointer which is an autorelease object pointer,
* it means that you needn't do a release operation unless you retain it.
*/
static CCString* stringWithContentsOfFile(const char* pszFileName);
2. Some Interfaces Changed
toInt ---> intValue toUint ---> uintValue toDouble ---> doubleValue toFloat ---> floatValue toBool ---> boolValue toStdStirng(deprecated) getCString(new api for getting c string)
3. Useful Macros
#define CCStringMake(str) CCString::stringWithCString(str) #define ccs CCStringMake
These macros can construct an autorelease CCString object more easily, e.g. If we want to new a lot of CCString object, and add them into a CCArray,
the following codes will achieve that and make your code more simple.
CCArray *stringArray = CCArray::arrayWithObjects(
ccs("Hello"),
ccs("Variable"),
ccs("Size"),
ccs("!"),
NULL);
CCDirector use CCLabelAtlas to show fps¶
If update your project from 1.1 to 2.0, you should add fps_images.png into Resources/, and add them in project configuration.
Modify some function names to make them more readable and more meaningful¶
All frequently used functions are marked in bold.
| function name pre-modify | function name after modification |
|---|---|
| CCCamera::getDirty | CCCamera::isDirty |
| CCConfiguration::isSupportsNPOT | CCConfiguration::supportsNPOT |
| CCConfiguration::isSupportsPVRTC | CCConfiguration::supportsPVRTC |
| CCConfiguration::isSupportsBGRA8888 | CCConfiguration::supportsBGRA8888 |
| CCConfiguration::isSupportsDiscardFramebuffer | CCConfiguration::supportsDiscardFramebuffer |
| CCConfiguration::isSupportsShareableVAO | CCConfiguration::supportsShareableAVO |
| CCNode::getIsVisible | CCNode::isVisible |
| CCNode::setIsVisible | CCNode::setVisible |
| CCNode::getIsRunning | CCNode::isRunning |
| CCGridBase::setIsTextureFlipped | CCGridBase::setTextureFlipped |
| CCRGBAProtocol::getIsOpacityModifyRGB | CCRGBAProtocol::isOpacityModifyRGB |
| CCRGBAProtocol::setIsOpacityModifyRGB | CCRGBAProtocol::setOpacityModifyRGB |
| CCLayer::getIsTouchEnabled | CCLayer::isTouchEnabled |
| CCLayer::setIsTouchEnabled | CCLayer::setTouchEnabled |
| CCMenu::getIsEnabled | CCMenu::isEnabled |
| CCMenu::setIsEnabled | CCMenu::setEnabled |
| CCParticleSystem::getIsActive | CCParticle::isActive |
| CCParticleSystem::getIsAutoRemovedOnFinish | CCParticle::isAutoRemovedOnFinish |
| CCParticleSystem::setIsAutoRemovedOnFinish | CCParticle::setAutoRemovedOnFinish |
| CCParticleSystem::getIsBlendActive | CCParticleSystem::isBlendActive |
| CCParticleSystem::setIsBlendActive | CCParticleSystem::setBlendActive |
| CCTexture2D::getIsHasPremultipliedAlpha | CCTexture2D::hasPremultipliedAlpha |
| CCFileUtils::setIsPopupNotify | CCFileUtils::isPopupNotify |
| CCFileUtils::setIsPopupNotify | CCFileUtils::setPopupNotify |
| CCScriptSupport::getIsMultiTouches | CCScriptSupport::isMultiTouches |
| CCScriptSupport::setIsVisible | CCScriptSupport::setVisible |
API changes in v2.0.2¶
- onEventCallback style
- CCTouchDelegate::ccTouchesBegan/Moved/Ended/Cancelled are renamed to onTouchesBegan/Moved/Ended/Cancelled
- CCTouchDelegate::ccTouchBegan/Moved/Ended/Cancelled are renamed to onTouchBegan/Moved/Ended/Cancelled
- CCKeypadDelegate::keyBackClicked(), keyMenuClicked() are renamed to onKeyBackClicked(), onKeyMenuClicked()
- CCAccelerometerDelegate::didAccelerate(...) is renamed to onAccelerometerChanged(...)
- add some convenient APIs into CCTouch
- locationInView() is renamed to getLocationInView()
- previousLocationInView() is renamed to CCTouch::getPreviousLocationInView()
- add getLocation() which returns OpenGL coordinates directly
- add getPreviousLocation() which returns OpenGL coordinates directly
- add getDelta() which returns the delta position between the current location and previous location in OpenGL coordinates
- CCGeometry, use object-orientated functions instead of static functions
- use p1.equals(p2) instead of CCPoint::CCPointEqualToPoint(p1, p2)
- use s1.equals(s2) instead of CCSize::CCSizeEqualToSize(s1, s2)
- use r.getMinX(), r.getMaxY() series instead of CCRect:CCRectGetMinX(r), CCRect::CCRectGetMaxY(r) series
- use r1.equals(r2) instead of CCRect::CCRectEqualsToRect(r1, r2)
- use r1.contrainsPoint(p1) instead of CCRect::CCRectContainsPoint(r1, p1)
- use r1.intersectsRect(r2) instead of CCRect::CCRectIntersectsRect(r1, r2)
- The param sequence of CCLabelTTF::create(label, dimension, hAlign, FontName, FontSize) is reordered CCLabelTTF::create(label, FontName, FontSize, dimension, hAlign ); to keep close with CCLabelTTF::create(label, FontName, FontSize). The param sequence is also adjusted in CCLabelTTF::initWithXxx series
