OMX Introduction -- Module OMX (Output MultipleXor)

OMX has been designed to give an API that uses the same calls to draw on different devices. It takes calls and redirect it to the selected output. In order to use OMX, you must first create a new VDS with OMXCreateVDS() and open a specific device using OMXOpenDevice()

What is a VDS?

A VDS is a Virtual Display Space. This is a structure in which OMX store all the needed information. When a device is opened, the specific information is kept there. At a higher level, this structure should not be accessed directly. There is a set of function, like OMXSetColor() or OMXSetSpeed(), to manipulate this structure.

What is a device?

For OMX, a device is the output to draw in. Right now, three devices have been planned:

SCR: The SCReen library to render graphics on a screen.
PRN: The PRiNter library to send graphics on a printer.
PSG: The PostScript Generator library to produce output using PostScript language

But only SCR is available for now.

When you open a device, it is stored inside VDS and OMX uses this information to redirect the command to the screen, the printer or the PostScript generator.

Here is the architecture of OMX.

                        OMX
                         |
                  +------+------+
                  |      |      |
                 SCR    PRN    PSG

Registering a Device

Because OMX is in C++ and some devices libraries might be in C, device can not register themself. This is why OMX must register all available device. Using the function RegisterOMXDevice(), OMX calls OMXRegister for every available device. By this way, there is only one place in all the source code that needs to be changed to add a new device in OMX. The function RegisterOMXDevice() should be called only once in the application. Every other call, during the application, will do nothing.

Device's specific information

Every devices need to be able to store specific information. In the VDS structure, there are two members to describe the selected output device.

   struct VDS_t
   {
   ...
   * ------------------------------------------------------------ *
   *      Device information                                      *
   * ------------------------------------------------------------ *
OMXDevice         *psOutputDevice;
OMXNativeMethod   *psNativeMethod;
   ...
   };

The psNativeMethod structure contains all the pointer for a device's set of function. The multiplexing is done using this information. In the OMXDevice structure, we have the name of the device and a void pointer. This pointer contains specific information for a particular device.

   struct OMXDevice_t
   {
char   *pszDeviceName;
void   *psMisc;
   };
   typedef struct OMXDevice_t OMXDevice;

For an OMX point of view, this structure cannot be accessed. Only the low level function should access this structure. eg: SCR store a SCRScreenDev structure containing the SGLDisplay, the SGLWindow and some other information specific to the screen.

Coordinate system

The coordinate system is set to have its (0,0) coordinates at the bottom left corner of each device. Coordinates are positive in the up and left direction. This default value may be changed using OMXSetOrigin(). The coordinate system may also be scaled with OMXSetVecScale(). With those functions, you can redefine all the coordinate system for particular needs

Redraw and Flush

There are two functions to control drawing in the device:

 OMXRedraw() and OMXFlush().

When you want to start a new drawing in the device you must reset it using the function OMXRedraw(). This function will clear the current output device and will put the raster in the background if needed.

After that, if you want to add new graphics to the current drawing, you can use all OMX drawing primitives.

When it is finished, you must send all changes to the output device. To do so, you must use OMXFlush(). In the case of a printing device, you must use it only at the end of the drawing process. For some other device like screen, it may be good to flush all graphical change sometime to show to the user that the system is working.

Scale in OMX

There are three scales in OMX:

 Representation Scale: Defined to be in representation
                       units per pixel (eg: mm/pixel)
 Vector Scale        : Defined to be in vector units per
                       pixel (eg: m/pixel)
 Raster Scale        : Defined to be the pixel size per pixel
                       on the output device. (not used yet)

About PCI Help Gateway