From 31189c8bddc154d2618d35f472917e593385f8de Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 26 Feb 2014 16:41:47 +0800 Subject: [PATCH] update releate note --- docs/RELEASE_NOTES.md | 287 ++++++++++++------------------------------ 1 file changed, 82 insertions(+), 205 deletions(-) diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index 75332c2fa9..c96e40cce0 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -88,11 +88,14 @@ * New Event Dispatcher * Physics integration * New GUI -* JavaScript remote debugger +* [JavaScript remote debugger](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/scripting/javascript/js-remote-debugger/en.md) * Remote Console support * Refactor Image - release memory in time and uniform the api of supported file format * Automatically generated Lua bindings, add LuaJavaBridge and LuaObjcBridge * Templated containers + * `CCDictionary` is replaced by `cocos2d::Map<>`, [usage](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/data-structure/v3/map/en.md) + * `CCArray` is replaced by `cocos2d::Vector<>`, [usage](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/data-structure/v3/vector/en.md) + * `CCBool`, `CCFLoat`, `CCDouble` are replaced with `cocos2d::Value`, [usage](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/data-structure/v3/value/en.md) # Features in detail @@ -152,7 +155,7 @@ auto item = MenuItemLabel::create(label, std::bind(&MyClass::callback, this, std // in v3.0 you can use lambdas or any other "Function" object auto item = MenuItemLabel::create(label, - [&](Ref *sender) { + [&](Object *sender) { // do something. Item "sender" clicked }); ``` @@ -176,7 +179,7 @@ Examples: | CCPointZero | Point::ZERO | | CCSizeZero | Size::ZERO | -The old values can still be used, but are not deprecated. +The old values can still be used, but are deprecated. ### override @@ -232,7 +235,7 @@ Examples: | ccDrawCircle() | DrawPrimitives::drawCircle() | | ccGLBlendFunc() | GL::blendFunc() | | ccGLBindTexture2D() | GL::bindTexture2D() | - | etc... | + | etc... | v2.1 free functions are still available, but they were tagged as deprecated. @@ -268,6 +271,10 @@ Examples: v2.1 methods are still available, but they were tagged as deprecated. +### Object is replaced with Ref + +Because the name `Object` is confused, so rename it to `Ref`, and remove functions that are not related with referenct count. All classes that inherit from `Object` now inherit from `Ref`. + ### getters Getters now use the `get` prefix. @@ -311,7 +318,7 @@ _Feature added in v3.0-beta and improved in v3.0-beta2_ The renderer functionality has been decoupled from the Scene graph / Node logic. A new object called `Renderer` is responsible for rendering the object. -Auto-batching ~~and auto-culling~~ support has been added. +Auto-batching and auto-culling support have been added. Please, see this document for detail information about its internal funcitonality: [Renderer Specification document](https://docs.google.com/document/d/17zjC55vbP_PYTftTZEuvqXuMb9PbYNxRFu0EGTULPK8/edit) @@ -323,7 +330,7 @@ TODO #### Auto-culling -TODO +With auto-culling, sprites that outside screen will be thrown away. #### Global Z order @@ -345,124 +352,31 @@ __Exceptions__: TODO -## Improved LabelTTF / LabelBMFont +## Improved LabelTTF / LabelBMFont / LabelAtlas _Feature added in v3.0-alpha0_ +`LabelTTF`, `LabelBMFont` and `LabelAtlas` will be replaced by new `Label`. The benifits of new `Label` are: + +* uniform api to create `LabelTTF`, `LabelBMFont` and `LabelAtlas` +* use `freetype` to generate texture for labels, which make sure that labels have the same effect on different platforms +* will cache textures to improve performance + ## New EventDispatcher _Feature added in v3.0-alpha0_ -All events like touch event, keyboard event, acceleration event and custom event are dispatched by `EventDispatcher`. +All events such as touch event, keyboard event, acceleration event and custom event are dispatched by `EventDispatcher`. `TouchDispatcher`, `KeypadDispatcher`, `KeyboardDispatcher`, `AccelerometerDispatcher` were removed. -### Adding Touch Event Listener +Features of `EventDispatcher` are: -For TouchOneByOne: -```c++ -auto sprite = Sprite::create("file.png"); -... -auto listener = EventListenerTouchOneByOne::create(); -listener->setSwallowTouch(true); -listener->onTouchBegan = [](Touch* touch, Event* event) { do_some_thing(); return true; }; -listener->onTouchMoved = [](Touch* touch, Event* event) { do_some_thing(); }; -listener->onTouchEnded = [](Touch* touch, Event* event) { do_some_thing(); }; -listener->onTouchCancelled = [](Touch* touch, Event* event) { do_some_thing(); }; -// The priority of the touch listener is based on the draw order of sprite -EventDispatcher::getInstance()->addEventListenerWithSceneGraphPriority(listener, sprite); -// Or the priority of the touch listener is a fixed value -EventDispatcher::getInstance()->addEventListenerWithFixedPriority(listener, 100); // 100 is a fixed value -``` +* dispatch events based on rendering sequence +* all events are dispatched by `EventDispatcher` +* can use `EventDispatcher` to dispatch custom events +* can register a lambda as call back function -For TouchAllAtOnce -```c++ -auto sprite = Sprite::create("file.png"); -... -auto listener = EventListenerTouchAllAtOnce::create(); -listener->onTouchesBegan = [](const std::vector& touches, Event* event) { do_some_thing(); }; -listener->onTouchesMoved = [](const std::vector& touches, Event* event) { do_some_thing(); }; -listener->onTouchesEnded = [](const std::vector& touches, Event* event) { do_some_thing(); }; -listener->onTouchesCancelled = [](const std::vector& touches, Event* event) { do_some_thing(); }; -// The priority of the touch listener is based on the draw order of sprite -EventDispatcher::getInstance()->addEventListenerWithSceneGraphPriority(listener, sprite); -// Or the priority of the touch listener is a fixed value -EventDispatcher::getInstance()->addEventListenerWithFixedPriority(listener, 100); // 100 is a fixed value -``` - -### Adding Mouse Event Listener ### -```c++ -auto mouseListener = EventListenerMouse::create(); -mouseListener->onMouseScroll = [](Event* event) { EventMouse* e = static_cast(event); do_some_thing(); }; -mouseListener->onMouseUp = [](Event* event) { EventMouse* e = static_cast(event); do_some_thing(); }; -mouseListener->onMouseDown = [](Event* event) { EventMouse* e = static_cast(event); do_some_thing(); }; -dispatcher->addEventListenerWithSceneGraphPriority(mouseListener, this); -``` - -### Adding A Keyboard Event Listener - -```c++ -auto listener = EventListenerKeyboard::create(); -listener->onKeyPressed = CC_CALLBACK_2(SomeClass::onKeyPressed, this); -listener->onKeyReleased = CC_CALLBACK_2(SomeClass::onKeyReleased, this); -EventDispatcher::getInstance()->addEventListenerWithSceneGraphPriority(listener, this); -``` - -### Adding An Acceleration Event Listener - -```c++ -auto listener = EventListenerAcceleration::create(CC_CALLBACK_2(SomeClass::onAcceleration, this)); -EventDispatcher::getInstance()->addEventListenerWithSceneGraphPriority(listener, this); -``` - -### Adding A Custom Event Listener - -```c++ -auto listener = EventListenerCustom::create("game_custom_event", [=](EventCustom* event){ - void* userData= event->getUserData(); - do_some_with_user_data(); -}); -dispatcher->addEventListenerWithFixedPriority(listener, 1); -``` - -### Dispatching A Custom Event - -```c++ -EventCustom event("game_custom_event"); -event.setUserData(some_data); -dispatcher->dispatchEvent(&event); -``` - -### Setting Fixed Priority For A Listener - -```c++ -dispatcher->setPriority(fixedPriorityListener, 200); -``` - -### Removing Event Listener - -#### Removing A Specified Event Listener - -```c++ -dispatcher->removeEventListener(listener); -``` - -#### Removing Custom Event Listener #### - -```c++ -dispatcher->removeCustomEventListener("my_custom_event_listener_name"); -``` - -#### Removing All Listeners For An Event Listener Type - -```c++ -dispatcher->removeEventListeners(EventListener::Type::TOUCH_ONE_BY_ONE); -``` - -#### Removing All Listeners - -```c++ -dispatcher->removeAllListeners(); -``` +Detail information of `EventDispatcher` can refer to [this document](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/input/event-dispatcher/en.md). ## Physics Integration @@ -529,26 +443,26 @@ _eventDispatcher->addEventListenerWithSceneGraphPriority(contactListener, this); Remove *cc* prefix for structure names in ccTypes.h, move global functions into static member functions, and move global constants into const static member variables. - | v2.1 struct names | v3.0 struct names | - | ccColor3B | Color3B | - | ccColor4B | Color4B | - | ccColor4F | Color4F | - | ccVertex2F | Vertex2F | - | ccVertex3F | Vertex3F | - | ccTex2F | Tex2F | - | ccPointSprite | PointSprite | - | ccQuad2 | Quad2 | - | ccQuad3 | Quad3 | - | ccV2F_C4B_T2F | V2F_C4B_T2F | - | ccV2F_C4F_T2F | V2F_C4F_T2F | - | ccV3F_C4B_T2F | V3F_C4B_T2F | - | ccV2F_C4B_T2F_Triangle | V2F_C4B_T2F_Triangle | - | ccV2F_C4B_T2F_Quad | V2F_C4B_T2F_Quad | - | ccV3F_C4B_T2F_Quad | V3F_C4B_T2F_Quad | - | ccV2F_C4F_T2F_Quad | V2F_C4F_T2F_Quad | - | ccBlendFunc | BlendFunc | - | ccT2F_Quad | T2F_Quad | - | ccAnimationFrameData | AnimationFrameData | + | v2.1 struct names | v3.0 struct names | + | ccColor3B | Color3B | + | ccColor4B | Color4B | + | ccColor4F | Color4F | + | ccVertex2F | Vertex2F | + | ccVertex3F | Vertex3F | + | ccTex2F | Tex2F | + | ccPointSprite | PointSprite | + | ccQuad2 | Quad2 | + | ccQuad3 | Quad3 | + | ccV2F_C4B_T2F | V2F_C4B_T2F | + | ccV2F_C4F_T2F | V2F_C4F_T2F | + | ccV3F_C4B_T2F | V3F_C4B_T2F | + | ccV2F_C4B_T2F_Triangle | V2F_C4B_T2F_Triangle | + | ccV2F_C4B_T2F_Quad | V2F_C4B_T2F_Quad | + | ccV3F_C4B_T2F_Quad | V3F_C4B_T2F_Quad | + | ccV2F_C4F_T2F_Quad | V2F_C4F_T2F_Quad | + | ccBlendFunc | BlendFunc | + | ccT2F_Quad | T2F_Quad | + | ccAnimationFrameData | AnimationFrameData | Global functions changed example ```c++ @@ -663,13 +577,13 @@ color3B = Color3B::WHITE; | ccGRAY | Color3B::GRAY | | kBlendFuncDisable | BlendFunc::BLEND_FUNC_DISABLE | -## Changes in the Lua bindings +# Changes in the Lua bindings -### Use bindings-generator tool for lua binding +# Use bindings-generator tool for lua binding Only have to write an ini file for a module, don't have to write a lot of .pkg files -### Bind the classes with namespace to lua +## Bind the classes with namespace to lua In previous, the lua binding can not bind classes that have the same class name but different namespaces. In order to resolve this issue, now the metatable name of a class is changed. For example, `CCNode` will be changed to `cc.Node`. This modification will affect some APIs as follows: @@ -681,7 +595,7 @@ In previous, the lua binding can not bind classes that have the same class name | tolua_pushusertype(tolua_S,(void*)tolua_ret,"CCFileUtils") | tolua_pushusertype(tolua_S,(void*)tolua_ret,"cc.FileUtils") | | tolua.cast(pChildren[i + 1], "CCNode") | tolua.cast(pChildren[i + 1], "cc.Node") | -### Use ScriptHandlerMgr to manage the register and unregister of Lua function +## Use ScriptHandlerMgr to manage the register and unregister of Lua function When we want to add register and unregister functions of Lua function for class, we need to change the declarative and defined files and then bind to Lua. In v3.0, we use the `ScriptHandlerMgr`. As an example, lets see the `MenuItem` class: @@ -700,83 +614,46 @@ In v3.0 version, we only need to add the `HandlerType` enum in the `ScriptHandle ScriptHandlerMgr:getInstance():registerScriptHandler(menuItem, luafunction,cc.HANDLERTYPE_MENU_CLICKED) ``` -### Use "cc"、"ccs"、"ccui" and "sp" as module name -The classes in the `cocos2d`、`cocos2d::extension`、`CocosDenshion` and `cocosbuilder` namespace were bound to lua in the `cc` module; -The classes in the `cocos2d::gui` namespace were bound to lua in the `ccui` module; -The classes in the `spine` namespace were bound to lua in the `sp` module; -The classes in the `cocostudio` namespace were bound to lua in the `ccs` module. +## Misc API changes -The main differences in the script are as follows: -```lua -// v2.x -CCSprite:create(s_pPathGrossini) -CCEaseIn:create(createSimpleMoveBy(), 2.5) +### Use `cc`、`ccs`、`ccui` and `sp` as module name -CCArmature:create("bear") +Now classes are binded into different modules instead of using global module. This will avoid conflicts with other codes. -ImageView:create() +* classes in `cocos2d`、`cocos2d::extension`、`CocosDenshion` and `cocosbuilder` were bound to `cc` module +* classes in `cocos2d::gui` were bound to `ccui` module +* classes in `spine` were bound to `sp` module +* classes in `cocostudio` were bound to `ccs` module +* global variables are binded to corresponding modules -// v3.0 -cc.Director:getInstance():getWinSize() -cc.EaseIn:create(createSimpleMoveBy(), 2.5) +Examples: -ccs.Armature:create("bear") +| v2.1 | v3.0 | +| CCDirector | cc.Director | +| CCArmature | ccs.Armature | +| kCCTextAlignmentLeft | cc.kCCTextAlignmentLeft | -ccui.ImageView:create() -``` +### Modified functions -### Deprecated funtions, tables and classes +Some global function names are renamed: -Add a lot of deprecate funtions、table and classes to support 2.x version as far as possible -Note: `Rect does not support the origin and size member variables` +| v2.1 | v3.0 | +| CCPoint/ccp | cc.p | +| CCRect | cc.rect | +| CCColor3B | cc.c3b | +| CCColor4B | cc.c4b | +| TODO: add others -### Use the Lua table instead of the some structs and classes binding +### Add some modules -Point、Size、Rect、Color3b、Color4b、Color4F、AffineTransform、FontDefinition、Array、Dictionary、PointArray are not bound. -The difference is as follow: -```lua -// v2.x -local pt = CCPoint(0 , 0) -local rect = CCRect(0, 0, 0, 0) -// v3.0 -local pt = cc.p(0, 0) -local rect = cc.rect(0,0,0,0) -``` +In the version 3.0, more modules were bound to lua, specific as follows: -Global functions about these classes are changed as follow: -```lua -// in v2.x -local pt = ccp(0,0) -local color3B = ccc3(0, 0, 0) -local color4B = ccc4(0, 0, 0, 0) +* physics +* spine +* XMLHttpRequest + +The `XMLHttpRequest` and `physics` are in the `cc` module, and the `spine` is in the `sp` module. Related test cases located in: -// in v3.0 -local pt = cc.p(0,0) -local color3B = cc.c3b(0,0,0) -local color4B = cc.c4b(0,0,0,0) -``` - -Through the funtions of the LuaBasicConversion file,they can be converted the Lua table when they are as a parameter in the bindings generator. - -### Integrate more modules into lua -In the version 3.0,more modules were bound to lua,specific as follows: - -``` -1.physics -2.spine -3.XMLHttpRequest -``` -The XMLHttpRequest and physics are in the "cc" module,and the spine is in the "sp" module. -The related test cases located in: - -``` -physics ---> TestLua/PhysicsTest -spine ---> TestLua/SpineTest -XMLHttpRequest ---> TestLua/XMLHttpRequestTest -``` - - - -## Known issues - -You can find all the known issues "here":http://www.cocos2d-x.org/projects/native/issues +* physics ---> TestLua/PhysicsTest +* spine ---> TestLua/SpineTest +* XMLHttpRequest ---> TestLua/XMLHttpRequestTest \ No newline at end of file