Developers Manual > Cocos2d-x > Modules > Scene Graph > Coordinate System

Coordinate System

version: Cocos2d-x v3.x
update: Updated about 2 years ago

Introduction of Different Coordinate Systems

Cartesian Coordinate System

You probably have known “Cartesian Coordinate System” from school where it’s heavily used in geometry lessons. If you have forgotten, these images will remind you quickly:

There’re 3 types of coordinate system that you will meet in mobile games development.

UI Coordinate System

In common UI Coordinates on iOS/Android/Windows SDK:

  • The origin (x=0, y=0) is at the top-left corner.
  • X axis starts at the left side of the screen and increase to the right;
  • Y coordinates start at the top of the screen and increase downward,

looks like this

Direct3D Coordinate System

DirectX uses Left-handed Cartesian Coordinate.

OpenGL and Cocos2d Coordinate System

Cocos2d-x/-html5/-iphone uses the same coordinate system as OpenGL, which is so called “Right-handed Cartesian Coordinate System”.

We only use x-axis & y-axis in 2D world. So in your cocos2d games:

  • The origin (x=0, y=0) is in the bottom-left corner of screen, which means the screen is in the first quartile of right-handed cartesian coordinate system,
  • X axis starts at the left side of the screen and increase to the right;
  • Y axis starts at the bottom of the screen and increase upwards.

And here’s a picture that helps illustrate Cocos2d-x Coordinates a bit better:

Note that it’s different from common UI coordinate systems and DirectX coordinate systems.

Parent and Childrens

Every class derived from Node (Ultimate cocos2d-x class) will have a anchorPoint property.
When determining where to draw the object (sprite, layer, whatever), cocos2d-x will combine both properties position and anchorPoint. Also, when rotating an object, cocos2d-x will rotate it around its anchorPoint.

We create a sprite as a gray parent and another sprite as blue child.Set parent’s position to Vec2(100,100),child’s anchor point in the center of circle .

C++ code:

1
2
3
4
5
6
7
8
9
10
Sprite* parent = Sprite::create("parent.png");
parent->setAnchorPoint(Vec2(0, 0));// Anchor Point
parent->setPosition(Vec2(100, 100));
addChild(parent);

//create child 
Sprite* child = Sprite::create("child.png");
child->setAnchorPoint(Vec2(0.5, 0.5));
child->setPosition(Vec2(0, 0));
parent->addChild(child);//add child sprite into parent sprite.

Lua code:

1
2
3
4
5
6
7
8
9
10
local parent = cc.Sprite:create("parent.png")
parent:setAnchorPoint(cc.p(0, 0))--Anchor Point
parent:setPosition(cc.p(100, 100))
self:addChild(parent)

--create child 
local child = cc.Sprite:create("child.png")
child:setAnchorPoint(cc.p(0.5, 0.5))
child:setPosition(cc.p(0, 0))
parent:addChild(child)--add child sprite into parent sprite.

Although we set child’s position of Vec2(0,0),parent’s position is Vec2(100,100).Therefore,child’s position is :

Anchor Point

The anchor point is used for both positioning and rotating an object. The anchor point coordinates are relative coordinates which usually correspond to a point within an object. For example, the anchor point Vec2(0.5, 0.5) corresponds to the center of the object. When setting the position of the object, the object is positioned such that the anchor point will be at the coordinates specified in the setPosition call. Similarly, when rotating the object, it is rotated about the anchor point.
For example, this sprite has an anchorPoint of Vec2(0,0) and a position of Vec2(0,0):

As a result, the sprite is positioned such that its anchor point is placed at the bottom left corner of its parent layer.

C++ code:

1
2
3
4
5
// create sprite
Sprite* sprite = Sprite::create("bottomleft.png");
sprite->setAnchorPoint(Vec2(0, 0));// Anchor Point
sprite->setPosition(Vec2(0,0));
addChild(sprite);

Lua code:

1
2
3
4
5
-- create sprite
local sprite = cc.Sprite:create("bottomleft.png")
sprite:setAnchorPoint(cc.p(0, 0))-- Anchor Point
sprite:setPosition(cc.p(0,0))
self:addChild(sprite);

In the following example, the relative nature of the anchor co-ordinates is demonstrated. The anchor point is assigned to be Vec2(0.5, 0.5), which corresponds to the center of the sprite.

C++ code:

1
2
3
4
5
// create sprite
Sprite* sprite = Sprite::create("center.png");
sprite->setAnchorPoint(Vec2(0.5, 0.5));// Anchor Point
sprite->setPosition(Vec2(0,0));
addChild(sprite);

Lua code:

1
2
3
4
5
--create sprite
local sprite = cc.Sprite:create("center.png")
sprite:setAnchorPoint(cc.p(0.5, 0.5))-- Anchor Point
sprite:setPosition(cc.p(0,0))
self:addChild(sprite);

As you can see, the center of the sprite is positioned at Vec2(0.5, 0.5). It can also be seen that the anchor point is not a pixel value. The X and Y values of the anchor point are relative to the size of the node.

getVisibleSize, getVisibleOrigin vs getWinSize

getVisibleSize returns visible size of the OpenGL view in points.The value is equal to getWinSize if don’t invoke GLView::setDesignResolutionSize().
getVisibleOrigin returns visible origin of the OpenGL view in points. Please refer to multiple resolution adaption for more details

How to convert coordinates

convertToNodeSpace

convertToNodeSpace will be used in, for example, tile-based games, where you have a big map. convertToNodeSpace will convert your openGL touch co-ordinates to the co-ordinates of the .tmx map or anything similar.

Example:

The following picture shows that we have node1 with anchor point (0,0) and node2 with anchor point (1,1).

We invoke
C++ code:

1
Vec2 point = node1->convertToNodeSpace(node2->getPosition()); 

Lua code:

1
local point = node1:convertToNodeSpace(node2:getPosition())

convert node2’s SCREEN coords to node1’s local.As the result,node2 with the position of (-25,-60).

convertToWorldSpace

convertToWorldSpace converts on-node coords to SCREEN coordinates.convertToWorldSpace will always return SCREEN position of our sprite, might be very useful if you want to capture taps on your sprite but need to move/scale your layer.
Generally, the parent node call this method with the child node position, return the world’s postion of child’s as a result. It seems make no sense calling this method if the caller isn’t the parent…

Example:
C++ code:

1
Point point = node1->convertToWorldSpace(node2->getPosition()); 

Lua code:

1
local point = node1->convertToWorldSpace(node2->getPosition()); 

the above code will convert the node2‘s coordinates to the coordinates on the screen.
For example if the anchor position of node1 is which will be the bottom left corner of the node1, but not necessarily on the screen. This will convert the position of the node2 which is to the screen coordinate of the point relative to node1 ). The result shows in the following picture:

convertToWorldSpaceAR

convertToWorldSpaceAR will return the position relative to anchor point: so if our scene - root layer has anchor point of Vec2(0.5f, 0.5f) - default, convertToWorldSpaceAR should return position relative to screen center.

convertToNodeSpaceAR - the same logic as for convertToWorldSpaceAR

Sample code:

C++ code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Sprite *sprite1 = Sprite::create("CloseNormal.png");
sprite1->setPosition(Vec2(20,40));
sprite1->setAnchorPoint(Vec2(0,0));
this->addChild(sprite1);

Sprite *sprite2 = Sprite::create("CloseNormal.png");
sprite2->setPosition(Vec2(-5,-20));
sprite2->setAnchorPoint(Vec2(1,1));
this->addChild(sprite2);

Vec2 point1 = sprite1->convertToNodeSpace(sprite2->getPosition());
Vec2 point2 = sprite1->convertToWorldSpace(sprite2->getPosition());
Vec2 point3 = sprite1->convertToNodeSpaceAR(sprite2->getPosition());
Vec2 point4 = sprite1->convertToWorldSpaceAR(sprite2->getPosition());

CCLOG("position = (%f,%f)",point1.x,point1.y);
CCLOG("position = (%f,%f)",point2.x,point2.y);
CCLOG("position = (%f,%f)",point3.x,point3.y);
CCLOG("position = (%f,%f)",point4.x,point4.y);

Lua code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
local sprite1 = cc.Sprite:create("CloseNormal.png")
sprite1:setPosition(Point(20,40))
sprite1:setAnchorPoint(Point(0,0))
self:addChild(sprite1)

local sprite2 = cc.Sprite:create("CloseNormal.png")
sprite2:setPosition(cc.p(-5,-20))
sprite2:setAnchorPoint(cc.p(1,1))
self:addChild(sprite2)

local point1 = sprite1:convertToNodeSpace(sprite2:getPosition())
local point2 = sprite1:convertToWorldSpace(sprite2:getPosition())
local point3 = sprite1:convertToNodeSpaceAR(sprite2:getPosition())
local point4 = sprite1:convertToWorldSpaceAR(sprite2:getPosition())

print(string.format("position = (%f,%f)",point1.x,point1.y))
print(string.format("position = (%f,%f)",point2.x,point2.y))
print(string.format("position = (%f,%f)",point3.x,point3.y))
print(string.format("position = (%f,%f)",point4.x,point4.y))

Result:

position = (-25.000000,-60.000000)
position = (15.000000,20.000000)
position = (-25.000000,-60.000000)
position = (15.000000,20.000000)

References

bottomleft.png (1.6 kB) iven, 2013-01-11 01:46

center.png (1.6 kB) iven, 2013-01-11 01:47

anchor_center.png (106.2 kB) iven, 2013-01-11 02:26

SpriteCoordinates.jpg (70 kB) iven, 2013-01-11 03:17

anchor_left.png (106.1 kB) iven, 2013-01-11 03:21

parent.jpeg (37.5 kB) iven, 2013-01-11 05:47

left-right-handed-cartesian.png (5.7 kB) walzer@cocos2d-x.org, 2013-01-11 06:57

opengl-coordinate-system.png (8.5 kB) walzer@cocos2d-x.org, 2013-01-11 07:12

ui-coordinate-system.jpeg (6.5 kB) walzer@cocos2d-x.org, 2013-01-11 07:19

convertToNodeSpace.jpg (7.2 kB) iven, 2013-02-19 09:36

convertToWorldSpace.jpg (7.3 kB) iven, 2013-02-19 09:36

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.