2. Hierarchy of graphical objects

Currently, the Vision Egg supports only a single screen (window). However, it is designed to run simultaneously in multiple screens, so once this capability is available (in SDL 2, hopefully), the following priciples will continue to apply.

Each screen contains a list of least one ``viewport''. A viewport is defined to occupy a rectangular region of the screen and define how and where objects are drawn. The default viewport created with each screen fills the entire screen. In the Vision Egg Viewport class, the screen position and size are specified in addition to the projection. The projection, specified by the Projection class, transforms 3D ``eye coordinates'' into ``clip coordinates'' according to, for example, an orthographic or perspective projection. (Eye coordinates are the 3D coordinates of objects referenced from the observers eye in arbitrary units. Clip coordinates are used to compute the final position of the 3D object on the 2D screen.) The default Projection created with a Viewport is an orthographic projection that maps eye coordinates in a one to one manner to pixel coordinates, allowing specification of object position in absolute pixels.

Multiple instances of the Viewport class may occupy the same region of the screen. This could be used, for example, to overlay objects with different projections such as in the targetBackground demo. The order of the list of viewports is important, with the first in the list being drawn first and later viewports are drawn on top of earlier viewports.

An instance of the Viewport class keeps an ordered list of the objects it draws. Objects to be drawn on top of other objects should be drawn last and therefore placed last in the list.

The objects a viewport drawns are all instances of the Stimulus class. The name ``Stimulus'' is perhaps a slightly inaccurate because instances of this class only define how to draw a set of graphics primitives. So for example, there are SinGrating2D and TextureStimulus subclasses of the Stimulus class.

The Vision Egg draws objects in a hierarchical manner. First, the screen(s) calls each of its viewports in turn. Each viewport calls each of its stimuli in turn. In this way, the occlusion of objects can be controlled by drawing order without employing more advanced concepts such as depth testing (which is also possible).