Fast Models Reference Manual: 5.5.5. C++ classes

5.5.5. C++ classes

This section describes the C++ classes and structures that are made available to you through the Visualisation Library. To make use of these classes, you must ensure that your LISA component begins with:

includes 
{	
#include “components/Visualisation.h”
}

Classes and structures described in this section are:

Class Visualisation

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

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 currently implemented using the Simple DirectMedia Layer (SDL) cross-platform rendering library.

Global functions

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

Class Visualisation

~Visualisation(): 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 should 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

The VisRegion class is the common base class for VisPushButtonRegion and VisRenderRegion, representing an arbitrary region of the visualization display.

~VisRegion(): This permits clients to delete a VisPushButtonRegion when it is no longer required.
void setId(void *id): This permits a client-defined identifier to be associated with the region.
void *getId(): This 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): This sets the location of this region relative to the visualization window.

Class VisPushButtonRegion : public VisRegion

The VisPushButtonRegion : public VisRegion 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 the following:

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

The VisRenderRegion : public VisRegion class defines a region of the visualization window that can render arbitrary client-drawn graphics, including a representation of the contents of an LCD.

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

VisRasterLayout const *lock(): Locks the region for client rendering. The VisRasterLayout structure is described elsewhere. See Struct VisRasterLayout. 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(): This 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): This causes the specified rectangle to be drawn to the GUI.
int writeText(const char *text, int x, int y): This 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

The VisRasterLayout 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 the following 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

The VisPixelFormat 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).

Copyright © 2008-2013 ARM. All rights reserved.	ARM DUI 0423O
Non-Confidential	ID060613
PDF version