1.16.3 Visualisation Library C++ classes

This section describes the Visualisation Library C++ classes and structures.

C++ classes inclusion

To use these Visualisation Library classes, begin your LISA component with the correct #include statement.

#include “components/Visualisation.h”

Visualisation class

This class provides access to the API for creating a custom LISA visualization component.

Visualisation class - about

A component obtains an instance of this class by calling the global function createVisualisation(). The component can then use this instance to control the size and layout of the visualization window.

The Visualisation Library is implemented using the Simple DirectMedia Layer (SDL) cross-platform rendering library.

Global functions

The global function is createVisualisation().

Visualisation *createVisualisation()
This generates an instance of the Visualisation Library. You can only call this function once, because SDL only supports opening a single display window.
Class Visualisation

This section describes the methods of the Visualisation class.

Destructor for the Visualisation Library. You must only call this method when your simulation is shutting down, after all allocated resources (VisRenderRegions, VisPushButtonRegions, VisBitmaps) have been deleted.
void configureWindow(unsigned int width, unsigned int height, unsigned int bit_depth)
This sets the visualization window to the requested size and bit depth. Depending on the display capabilities, the window might actually get a different bit depth from the size you requested.
VisBitmap *loadImage(char const *filename)
This allocates a new VisBitmap object, initialized by loading a Microsoft Windows Bitmap (.BMP) from the given file.
VisBitmap *loadImageWithAlphaKey(char const *filename, unsigned int red, unsigned int green, unsigned int blue)
This allocates a VisBitmap object, as with loadImage(). All pixels of the color specified by red, green, blue are converted into a transparent alpha channel.
VisBitmap *cropImage(VisBitmap *source, int x, int y, unsigned int width, unsigned int height)
This allocates a new VisBitmap object, by cropping a region from the source bitmap.
void releaseImage(VisBitmap *)
This releases the resources held by the given VisBitmap. The underlying bitmap is only be unloaded if it is not in use.
void setBackground(VisBitmap *background, int x, int y)
This sets the background image for the visualization window. This takes a copy of the data referenced by the VisBitmap, so it is safe for the client to call releaseImage(background) immediately after calling setBackground(). The background is not displayed until the first call to poll().
VisRenderRegion *createRenderRegion()
This allocates a new VisRenderRegion object that can be used to display arbitrary graphics, including LCD contents, in a rectangular region.
VisPushButtonRegion *createPushButtonRegion()
This allocates a new VisPushButtonRegion, which can be placed at a location on the display to provide a clickable push button.
bool poll(VisEvent *event)

This call permits the Visualisation Library to poll for GUI events. The client passes a reference to a VisEvent structure, which receives details of a single mouse/keyboard event.

The method returns false if no events have occurred.

Your LISA visualization implementations must call this periodically by using a GUIPoll component. On each gui_callback() event, you must ensure that the visualization component repeatedly calls poll() until it returns false.

void lockMouse(VisRegion *region)
This method locks the mouse to the visualization window and hides the mouse pointer.
void unlockMouse()
This unlocks and redisplays the mouse pointer.
bool hasQuit()
This returns true if the user has clicked on the close icon of the visualization window.

Class VisRegion

This class is the common base class for VisPushButtonRegion and VisRenderRegion, representing a region of the visualization display.

Permits clients to delete a VisPushButtonRegion when it is no longer required.
void setId(void *id)
Permits a client-defined identifier to be associated with the region.
void *getId()
Returns the client-defined identifier.
void setVisible(bool vis)
Specifies whether the region is to be displayed on the screen. This is currently ignored by the SDL implementation.
void setLocation(int x, int y, unsigned int width, unsigned int height)
Sets the location of this region relative to the visualization window.

Class VisPushButtonRegion : public VisRegion

This class defines a region of the visualization window that represents a clickable button.

Optionally, the button can provide different VisBitmap representations for a button-up and a button-down graphic, and a graphic to use when the mouse pointer rolls over the button.

In addition to the public method defined in VisRegion, this class defines these methods:

void setButtonUpImage(VisBitmap *bmpUp) : void
setButtonDownImage(VisBitmap *bmpDown) : void
setButtonRollOverImage(VisBitmap *bmpRollover)

Sets the graphics to be used for each of the button states. If any image is not specified or is set to NULL, then the corresponding area of the visualization background image is used.

The VisPushButtonRegion takes a copy of the VisBitmap, so the client can safely call Visualisation::releaseBitmap() on its copy.

void setKeyCode(int code)
This sets the code for the keypress event that is generated when the button is pressed or released.

Class VisRenderRegion : public VisRegion

This class defines a region of the visualization window that can render client-drawn graphics, including a representation of the contents of an LCD.

In addition to the public method defined in VisRegion, the class defines these methods:

VisRasterLayout const *lock()
Locks the region for client rendering. While the buffer is locked, the client can modify the pixel data for the buffer. You must not call the methods writeText() and renderBitmap() while the buffer is locked.
void unlock()
Releases the lock on the render buffer, permitting the buffer to be updated on screen.
void update(int left, int top, unsigned int width, unsigned int height)
Causes the specified rectangle to be drawn to the GUI.
int writeText(const char *text, int x, int y)
Renders the given ASCII text onto an unlocked VisRenderRegion. The return value is the x co-ordinate of the end of the string. The default font is 8 pixels high, and cannot be changed.
void renderBitmap(VisBitmap *bitmap, int x, int y)
Draws a bitmap onto an unlocked VisRenderRegion.

Struct VisRasterLayout

This struct defines the layout of the pixel data in a frame-buffer.

The lock() method of the LCD protocol expects to be given a pointer to this structure. You can generate a suitable instance by calling VisRasterRegion::lock().

The structure contains these fields:

uint8_t *buffer
This points to the buffer for the rasterized pixel data. The controller can write pixels into this buffer, but must stick within the bounds specified by the width and height.
uint32_t pitch
The number of bytes between consecutive raster lines in the pixel data. This can be greater than the number of bytes per line.
uint32_t width
The width, in pixels, of the render area. This value can be less than the width requested by the LCD controller when it called lock().
uint32_t height
The height, in pixels, of the render area. This value can be less than the height requested by the LCD controller when it called lock().
VisPixelFormat format
This structure defines the format of the pixel data in the raster buffer.
bool changed
This is set to true if the pixel format or buffer size has changed since the previous call to lock().

Pixel data is represented as a one-dimensional array of bytes. The top-left pixel is pointed to by the buffer member. Each pixel takes up a number of bytes, given by format.pbytes.

The pixel at location (x, y) is stored in the memory bytes starting at buffer[y * pitch + x * format.pbytes].

Struct VisPixelFormat

This struct specifies the format of pixel data within the buffer.

The members are:

uint32_t rbits, gbits, bbits
The number of bits per color channel.
uint32_t roff, goff, boff
The offset within the pixel data value for the red/green/blue channels.
uint32_t pbytes
The size of a single pixel, in bytes.

format.pbytes specifies the number of bytes that make up the data for a single pixel. These bytes represent a single pixel value, stored in host-endian order. The pixel value contains a number of the form (R<<format.roff) + (G<<format.goff) + (B<<format.boff), where (R,G,B) represents the values of the color channels for the pixel, containing values from 0 up to (1<<format.rbits), (1<<format.gbits), (1<<format.bbits).

Non-ConfidentialPDF file icon PDF version100964_1110_00_en
Copyright © 2014–2020 Arm Limited or its affiliates. All rights reserved.