| |||
Home > Peripheral and Interface Components > Visualisation Library > 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:
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.
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.
~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.
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.
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.
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.
renderBitmap(VisBitmap
*bitmap, int x, int y)
Draws a bitmap onto an unlocked VisRenderRegion.
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
*
bufferThis 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
pitchThe number of bytes between consecutive raster lines in the pixel data. This can be greater than the number of bytes per line.
uint32_t
widthThe 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
heightThe 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
formatThis 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]
.
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.
roff, goff,
boff
The offset within the pixel data value for the red/green/blue channels.
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)
.