Coordinate Systems
Contents
a2dCanvas uses a rectangular world coordinate system that is in Unit X,Y, which means that vertexes can be meters, inch as well as bigs versus time. How large a2dCanvasObjects are on the screen is not coupled with the units, all coordinates are stored as doubles or longs.
When mapping the whole or part of a a2dCanvasDocument to the window the programmer can decide that one centimeter is indeed one centimeter on the screen also. When rendering a a2dCanvasObject its data is converted/ presented into basic primitives defined in world coordinates, those primitives can be drawn with the active a2dCanvasView.
Often the data in the canvas object is directly related to the basic primitives e.g width and height of a rectangle object, but this is not a must. How the basic primitive coordinates are displayed on a certain a2dCanvasView view, is defined by the view's mapping.
2D only
The a2dCanvasView views are designed for 2D (because of layers, actually 2.5D), and you can only draw in 2D on it.
So if you put a 2D projection of the world map in a a2dCanvasDocument, you can tell a a2dCanvasView to only display Amsterdam. Even if the world object itself is really 3D, and inside the mya2dCanvasWorldObject it is/ can be stored as 3D coordinates, the drawing of Amsterdam will and needs to be 2D.
3D to 2D
Therefore in such a situation when rendering part of the 3D world object, this part is first projected to 2D within the object itself. Of course you can do this projection in such a manner that e.g. a cube is eventually drawn as a 3D cube, but using 2D drawing methods. The projection task from 3D to 2D can be done via a matrix which transforms the 3D coordinates inside the mya2dCanvasWorldObject to 2D coordinates. One can of course use any kind of data within a a2dCanvasObject, as long as the generated drawing is in 2D.
2D to View
This 2D drawing is placed relative to the parent a2dCanvasObject of the actual object to render. When rendering the object those coordinates will be transformed to an absolute position, which is defined by the accumulated matrix on the path leading from some top object in the a2dCanvasDocument to the mya2dCanvasWorldObject to render.
After this transformation to absolute 2D coordinates there is a second transformation inside a2dCanvasView, which defines the viewport. The viewport is best described as the eye position in 2D. This second transformation, transforms absolute coordinates to window coordinates. In practice a total transform matrix is set for a2dCanvasView to do both the transformation to absolute followed by translation into device in one matrix.
Using a square coordinate system is recommended. Meaning the projection from world to device coordinates is the same in X and Y. Although every transformation from object to view is 2 dimensional, the object itself is totaly free in generating the 2D canvas objects/ primitives representing the object in some way. Those 2D objects will be drawn with the a2dCanvasView that is given as a parameter to the object rendering function via its a2dIterC pointer when it is rendered.