Coordinate systems in Guiliani

Different graphic systems typically also differ in the way in which they treat coordinates. For instance OpenGL by definition places its origin in the lower-left corner of the screen, whereas a standard framebuffer is likely to have its origin in the top-left corner. Systems capable of dealing with subpixel coordinates will differ in details such as whether integer coordinates point to the center of pixels, or to the edges between them. This page specifies how Guiliani's internal coordinate systems work.

The origin

Guiliani's coordinate system places the origin (x=0, y=0) at the center of the top-left pixel.

Relative coordinates vs. Absolute coordinates

There are two elementary types of coordinate which you will need to understand: Relative coordinates and Absolute Coordinates.

Absolute coordinates are absolute pixel positions in screen space. (0,0) refers to the pixel in the top left corner of the screen area accessible to GUILANI. You will usually use absolute coordinates for drawing operations inside your object's DoDraw() method.

See also: CGUIObject::GetAbsXPos(), CGUIObject::GetAbsYPos()

Relative coordinates are given in a local coordinate system, whose origin is defined by the top left corner of a control's parent object. (0,0) does therefore not refer to the origin of the entire screen, but to the top left corner of the parent object, thus allowing you to easily position objects inside of containers. It is absolutely legal to position an object outside of the visible area of its parent (e.g. at negative pixel positions), but be aware that it will be clipped against the parent's dimensions and might thus not be visible at all.

See also: CGUIObject::GetRelXPos(), CGUIObject::GetRelYPos()

The example screenshot below demonstrates the difference between absolute and relative coordinates. The red arrows represent the absolute coordinates of the two objects marked with yellow rectangles. The green arrow shows the relative coordinate of the "close" button, which is a child object of the larger popup window.

Visible coordinates vs. current coordinates

One pitfall when working with coordinates is the hierarchical dependency between objects in the object tree. As we know, a child object's absolute coordinate will change if one of its parent object's moves across the screen. (The relative coordinate will of course remain untouched). Now you might expect that such a movement of a container object will have immediate effect on its children - but have a look at the following example code:

CGUICompositeObject* pParentObject = new CGUICompositeObject( &GETGUI, 0, 0, 100, 100); // Creates a container
CGUIObject* pChildObject = new CGUIObject( pParentObject, 10, 10, 50, 50);              // Creates a child object inside the container
pChildObject->GetRelXPos();         // returns 10
pParentObject->SetRelXPos(100);     // Moves the parent's x position to 100
pChildObject->GetRelXPos();         // returns also 10
pChildObject->GetAbsXPos();         // surprisingly still returns 10
pChildObject->GetCurrentAbsXPos();  // returns 110

You probably would have expected that the child object's absolute coordinate does reflect the change of the parent's position immediately. But in fact this will only be updated during the GUI's next redraw-cycle. In other words: The absolute coordinates always represent your object's positions as they can currently be seen on the screen. If you do for some reason need to have access to the latest absolute position of an object, call the GetCurrentXXX methods instead, which will return the actual positions at that time.

See also: CGUIObject::GetCurrentAbsXPos(), CGUIObject::GetCurrentAbsYPos()