Blinky’s Blog

Part Two

eyeGT is written in C++ thus its logic and operations are heavily based on the Object Oriented (OO) paradigm. Unlike most other graphic libraries, eyeGT provides a monolithic access to the whole library, the application doesn’t have to deal with objects allocation and freeing, saving pointers etc. as eyeGT itself will perform these operations when needed. The advantages of such architecture are multifold:

• Reduced memory fragmentation: eyeGT allocates a chunk of memory and uses it as a pool to allocate objects in it, performing housekeeping (garbage collection) when required. This alone guarantees that your application will never experience memory leakages owing to unreleased objects.
• Better control over memory allocation: objects are instantiated only when required and released when no longer needed. The application doesn’t have to worry about when to release memory, eyeGT will do it when most appropriate, without degrading the performance of the application.
• Reduce time to develop: programmer doesn’t need to debug the graphic library, Barefoot Software using the latest technologies in problem tracking and solving did the job already, so you can concentrate on the architecture of your application instead of solving other libraries’ problems.
• Portability: whatever the platform, processor and quantity of memory are, eyeGT can be ported to it; a C++ compiler is the only needed tool. eyeGT doesn’t uses RTTI and exceptions, as most embedded systems C++ compilers do not support them; extensive error description is returned by each API to allow for problems easy pinpointing. In case of any error, the application will never crash owing to eyeGT inability to handle an error; this is a very stringent and at the same time basic requirement for any technology that is mean to use in a production environment that can put life at risk like: airplanes displays, life maintenance machines or nuclear facilities.

The OO paradigm of eyeGT is not only used internally by the code but it is extended to all the operations and services that an application may require from it. In most of the other graphical libraries or toolkits, the application has to have total control over the drawing process: it has to call the appropriate method in the correct order with the right timing and has to respond to a series of messages coming from the hosting operating system to correctly display graphical elements. There is no way of storing graphical objects in a OO manner within the library itself and just instructing them to repaint themselves when they need to be updated. With such a scheme even simple effects like making a blinking object will turn quickly into a daunting task. Even if lately some libraries have appeared on the market (like GDI+ and others) they require an enormous quantity of resources to run and cannot be ported to embedded systems.

eyeGT takes a completely different approach:

The application no longer has access the drawing surface directly, in order to visualize something on the screen the application needs to create a visual object (like an eyeGT shape), place some drawing commands on it and finally place the shape on the screen. eyeGT uses a dictionary based system (Particle Dictionary) to keep track of every particle (shape, sound, container, button etc) created by the user application.

When a method to place a particle is invoked (i.e. egtPlaceParticleInstance), eyeGT put an instance of the selected particle in the canvas; actually, the instance is placed in the Display List and when the latter is processed using the egtProcessDisplayList method the resulting shape is drawn on the canvas.

Think about the Particle Dictionary as a list of class templates and when a particle is placed on the canvas eyeGT creates an instance of that template as in the diagram below:

Of course it is possible to place many instances of a particle on the canvas, as below:

Particle Dictionary

Concept of particle

eyeGT uses Particles and Instances of particles to perform its operation. A particle is a visible (or in certain cases not visible) ‘template’ that defines a certain object; all the particles are stored in a list known as the Particle Dictionary handled transparently by eyeGT itself. For example: a shape particle is an object template that contains drawing instruction like egtLineTo or egtQuadricCurveTo issued in a fashion  that represents, always for example, a square. Creating a particle does not mean making something visible on the screen, but merely defining its ‘template’, ‘model’ or in eyeGT parlor a ‘particle’.  To show the defined particle in the canvas, it is necessary to call the egtPlaceParticleInstance function; to give some C++ parallelism: as it is possible to create many instances (objects) of a given C++ class and change values of its members (properties), in eyeGT it is possible to call the egtPlaceParticleInstance function several times for the same particle and then modify the visual appearance (properties) of any of the instances independently from each other.

To each particle in the Particle Dictionary is assigned a unique ID. The ID is a non-signed two bytes numerical value that ranges from1 to 65,535; the value 0 is reserved by eyeGT to hold a special particle, the root particle, as discussed in the next chapter. The application may choose the ID assigned to each particle as it wishes; note that the ID is a mere identifier for the particle, so particlea that have a lesser ID number (i.e.: 10) have no special attributes (like display priority for example) when compared to other particle that have bigger ID values (i.e.: 100).

Being unique, two particles cannot have the same ID, if for some reason the application need to have a particle with an ID already being using by another particle (even of a different type), it needs to free the other particle by calling the egtReleaseParticle method and then create the new particle with the same ID. Given the limitation above, an application may define up to 65,535 different particles, but the number of instances is actually unlimited. Note that the maximum number of particle is dictated by the limitations of the system hosting the application, like memory availability, more than the range limit of the ID itself.

Particle memory allocation

When creating a particle, the system automatically reserve memory to contain it; sometime, particles require defining data to be passed as creation time, like the binary definition of a shape loaded from a disk file, as in the code below:

egtLoadShape(eyeGTCanvas, pidREDRECTANGLE, lpData, Data, true);

when this line gets executed, eyeGT will attempt to create a shape particle, assign to it the ID represented by the enum pidREDRECTANGLE (i.e.: 100) and copy the data contained in the buffer pointed by lpData into its own internal buffer. This way of operating may create some problems when dealing with devices with limited memory, as at one time there are two copies of the same data in memory. To override this situation, eyeGT provides the CopyData parameters on all the data loading functions like egtLoadShape, egtLoadFont etc. If false is specified for CopyData, eyeGT will NOT copy the data in the lpData buffer, but will save a pointer to the data itself, so the application has the responsibility of allocating and preserving the block of memory until eyeGT will need it. The memory block can be released when the particle is not being currently used (i.e.: a shape particle displayed or a sound particle being played) and has been removed from the Particle Dictionary using the egtReleaseParticle method. If true will be specified for CopyData, the application may free the buffer pointed by lpData as soon after the data loading functions have been executed.