Lothario
/
axmol
mirror of https://github.com/axmolengine/axmol.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5473 from minggo/release-note 

update releate note
This commit is contained in:
minggo 2014-02-26 16:49:27 +08:00
parent c86aeda15e 31189c8bdd
commit 31ca646b7e
1 changed files with 82 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
docs/RELEASE_NOTES.md
View File

@ -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
@ -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<Touch*>& touches, Event* event) { do_some_thing(); };
listener->onTouchesMoved = [](const std::vector<Touch*>& touches, Event* event) { do_some_thing(); };
listener->onTouchesEnded = [](const std::vector<Touch*>& touches, Event* event) { do_some_thing(); };
listener->onTouchesCancelled = [](const std::vector<Touch*>& 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<EventMouse*>(event); do_some_thing(); };
mouseListener->onMouseUp = [](Event* event) { EventMouse* e = static_cast<EventMouse*>(event); do_some_thing(); };
mouseListener->onMouseDown = [](Event* event) { EventMouse* e = static_cast<EventMouse*>(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
@ -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)
```
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)
// 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
* spine
* XMLHttpRequest
```
physics ---> TestLua/PhysicsTest
spine ---> TestLua/SpineTest
XMLHttpRequest ---> TestLua/XMLHttpRequestTest
```
The `XMLHttpRequest` and `physics` are in the `cc` module, and the `spine` is in the `sp` module. Related test cases located in:
## 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