Platform Package reference: Function EwInitViewport()

Description of the function EwInitViewport() available in all Platform Packages for C compatible target systems. This function is intended to be used when integrating the Embedded Wizard created GUI application with the underlying graphics subsystem, graphics hardware or other external GUI applications coexisting on the same system.

Declaration

XViewport* EwInitViewport

(

  XPoint          aSize,

  XRect           aExtent,

  XInt32          aOrient,

  XInt32          aOpacity,

  void*           aDisplay1,

  void*           aDisplay2,

  void*           aDisplay3,

  XViewportProc   aProc

)

Parameters

aSize

Size of the viewport in pixel. This is the area where graphics outputs will occur. Depending on the use case (see below), this parameter determines the size of the framebuffer to create or the size of an already existing framebuffer to use.

aExtent

Position and size hint, where the created framebuffer should be shown on the screen. If the size of aExtent differs from aSize, the framebuffer content should be scaled in order to fit in the aExtent area. Please note: The area is already expressed in coordinates valid within the target display by taking in account all particular configuration aspects like the default rotation of the surface contents.

aOrient

Orientation hint. The meaning of this parameter depends on the target system. For example, OpenGL target uses aOrient to determine the screen rotation in degrees.

aOpacity

Opacity value for the created framebuffer in the range 0 .. 255. 0 = fully transparent. 255 = fully opaque.

aDisplay1, aDisplay2, aDisplay3

Platform dependent parameter, where already existing framebuffer or some drawing context, etc. is passed.

aProc

Optional callback function XViewportProc to be called when viewport update has been done. The callback function can then perform some target system particular tasks to complete the screen update, etc. If NULL, no callback is called.

Discussion

The function EwInitViewport() prepares a new viewport. Viewports provide a kind of abstraction of the physical framebuffer or display where graphical outputs are drawn. Depending on the particular target system there are two mayor approaches how Graphics Engine can deal with a framebuffer:

1.The creation and the initialization of the framebuffer are performed by the Graphics Engine in the particular platform adaptation layer. In this case Graphics Engine maintains the full control and the ownership over the framebuffer. The Graphics Engine can show, hide and reconfigure the framebuffer every time. Therefore the viewport API provides functions which allow the main software or other external software parts to change the framebuffer configuration - in a platform independent way.

In this use case, the arguments passed to EwInitViewport() are used to create and configure a new framebuffer and finally to arrange it on the display. These configuration can be changed later by EwConfigViewport().

2.The framebuffer creation and its initialization are tasks of the main software, external frameworks, the operating system, etc. This means, the framebuffer control lies completely beyond the Embedded Wizard. The Graphics Engine is limited to draw into this framebuffer. The ownership and the framebuffer configuration are aspects of the main software or the external framework only.

In this use case, EwInitViewport() receives a reference to an existing framebuffer or other kind of graphical context where drawing operation will take place and stores it internally. Optionally, EwInitViewport() can create a private, internal off-screen surface which is used as the framebuffer. When screen update is performed, Graphics Engine copies the affected area from the off-screen surface into the framebuffer or display passed to the EwInitViewport() function.

After a viewport has been initialized, screen updates can be performed. To do this the functions EwBeginUpdate(), EwBeginUpdateArea() are intended. These functions cover the internal aspects of the framebuffer access, the double buffering, V-Sync, etc.

If not used anymore, viewports should be freed by EwDoneViewport(). The function is usually called at the startup time during the Initialization of the GUI Application. If successful, the function returns a pointer to a XViewport structure representing the viewport. If the initialization is failed NULL is returned.