Pluto 6 Software

Software Documentation Guide

The Pluto 6 controller board software documentation is supplied in Compiled Help format. Documentation topics and pages can be accessed in the following ways:

  • Click on the Contents tab at the top of the left hand window and expand each of the documentation books to view the topic pages. Click on a topic page to display the contents in the right hand window.
  • Click on the Index tab at the top of the left hand window to search through the indexed topics in the compiled help file. Type the topic that you are looking for in the edit box at the top of the left hand window and the relevant topic will be highlighted in the index list. Click on the highlighted item to view the associated page.
  • Click on the Search tab at the top of the left hand window to perform a key word search of the whole of the software user guide. Type the key word that you wish to search for in the edit box at the top of the window and click the List Topics button. All of the pages that contain the key word that you entered will be listed below. Each of the pages found will have the number of times that the key word appears in the page. To view a particular page listed click on the page title and click the Display button.
  • Click on the Favorites tab at the top of the left hand window to store your on set of links to particular help pages. To add a page to your lists of favorites first find the page and display it in the left window using one of the three methods listed above. Click the Add button at the bottom of the left window to add the topic to your list of favorites. To view a page in your favorites list click on the topic name in the list. To remove a topic click on the topic name and click the Remove button.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.
Document No: 80-17314, Issue 13 Release Date: 08.06.09 Email: support@heber.co.uk www.heber.co.uk


Pluto 6 Software

Software Updates

The software that is supplied with the Pluto 6 Development Kit is the current version at the time that the product was released. Periodically the Heber Pluto 6 software will be revised. The latest software can be downloaded from the Heber website: www.heber.co.uk

It is recommended that you check the website and download the latest version of the software drivers before starting your game development. Release Notes are also provided on the website giving information regarding changes made for each version of the software.

If you experience problems with the software during game development please check the website to ensure that you are using the latest versions of the software.

For further information, or to report any problems with the Pluto 6 software, email Heber Technical Support: support@heber.co.uk

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Software

Software Overview

The Pluto 6 controller board is supplied with a suite of software to allow developers to create gaming applications.

Software Libraries

Structured software libraries with an Application Programming Interface (API) in the C programming language provide the following:

  • Access to the Pluto 6 hardware.
  • High level peripheral device controllers.
  • Example drivers that can be used as a template for writing custom drivers.
  • Demonstration project software that can be used as a template for gaming application development.

Application Module

The source code for example projects is supplied to provide a starting point for game development. The following projects are supplied:

  • Standard demonstration project demonstrating use of the Pluto 6 software API.
  • Dual Video project using the Advanced Video and Audio Drivers, and 2 Calypso 32 video cards.
  • Touchscreen demonstration project.
  • Boot loader project to demonstrate loading game code from a Compact Flash card.

Tools and Utilities

Where particular data formats are required ensure optimum performance from the Pluto 6 platform file pre-processing tools and utilities are provided. The tools and utilities can be run from the command line in a MS-DOS window.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Software Getting Started

Running your Code on Pluto 6

Built projects in the project directory can be loaded on to the Pluto 6 control board in the following ways:

From Compact Flash

  • Ensure that the boot flash programmed with the boot loader project is fitted into socket U1 on the Pluto 6 control board.
  • Ensure that the output file from the project that you have built is called demo.s19 if it is a non-video project or vdemo.s19 if it is a video project.
  • Copy the .s19 file to the root directory of the Compact Flash card using the Compact Flash reader/writer.
  • Fit the the Compact Flash card into the CF SLOT on the Pluto 6 board.
  • Power the board up and the project will be loaded into DRAM and execute.
    Note: If you are running a dual video project, two Calypso 32 Video Cards must be fitted to expansion connectors EXP 0 and EXP 1 on the Pluto 6 board.
    Note: If you are running a single video project, one Calypso 32 Video Card must be fitted to expansion connector EXP 1 on the Pluto 6 board.

Using the P&E® ICD Debugger

  • Ensure that the ICD software is installed and the debug module attached to both Pluto 6 and your PC.
  • Power up the Pluto 6 board and launch the P&E® ICDCFZ ColdFire® ICD software.
  • Click the Reset button on the software tool bar to reset the ColdFire® on the Pluto 6.
  • Click the Go button on the software tool bar to execute the code in the boot flash. This code will run the Pluto 6 entry code and set up the chip select registers on the ColdFire®.
  • After a few seconds click the Stop button on the software tool bar to stop the boot flash code executing.
    Note: Do not reset the CPU at this point because the chip select settings set by the boot flash code will be cleared.
  • Click the Load button on the software tool bar, select the .s19 file that you wish to load (e.g. demo.s19) and click Open.
    In the ICD software Status Window a Loading.... message will appear. When the .s19 file has loaded a loaded message will appear in the Status Window.
  • Type loadmap and choose the .map file to load the symbols.
  • Type pc entry, to set the program counter to the beginning of the program.
  • To reinitialise the processor to a supervisor mode, type SR 2700 into the Status Window edit box and press Enter.
  • Type br Game to a breakpoint at the beginning of function Game.
  • Type go to run the program. The debugger will stop when it reaches the breakpoint.

Further Information

For further information on running your code on Pluto 6 refer to Using the Development Kit in the Pluto 6 Development Kit User Manual. This manual (Heber part number 80-18463) is included on the Pluto 6 Dual Video Development Kit CD-ROM.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Application Module

The Application Module provides a starting point for developers to write gaming applications. Files within the module allow the configuration and installation of device drivers provided by the library modules, and provide a basic framework for game development. The source code is supplied for this module.

Application Examples

The following example applications are provided that can be used as a template/starting point for game development:

Example Project | Description
Standard Demonstration Project | Standard project demonstrating use of the Pluto 6 software API.
Dual Video Project | Video project using the Advanced Video and Audio drivers, Dual Video drivers and Calypso 32 video cards.
Touchscreen Project | Touchscreen demonstration project demonstrating how to use a touchscreen with Pluto 6.
Boot Loader Project | Boot loader project demonstrating loading game code from a Compact Flash card.

Module Components

The Application Module example projects are built using a standard set of component files. For a description of the main source files in the Application Module click here.

See Also

  • GNU Compiler
  • Software Conventions
  • Software Architecture
  • Source File Types
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Install Device Drivers API Function

Application Module

Module Components

The Application Module comprises of the following main components:

Component | Description
demo.c | This is the file the game/demonstration program is located.
game.c | This file provides the entry point to the game application.
config.c | This file allows the game developer to specify driver configuration options.
devices.c | This file specifies the device drivers that will be loaded for the project.
fpga.c | This file specifies the memory mappings for the Pluto 6 FPGA.
sysram.c | This file allows variables to be declared that are stored in non-volatile memory.
idram.c | This file allows variables whose values must be preserved to be stored in non-volatile memory.

See Also

  • GNU Compiler
  • Software Conventions
  • Source File Types
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


demo.c

This file provides a template for the development of gaming applications. In the supplied software the file demo.c contains a function DemoFnc() which is called from the function Game(). This functions contains the source code for the demonstration program.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


game.c

This module contains function ‘Game()’. After system initialisation this function calls DemoFnc() and enters an infinite loop until the user ends the program.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


config.c

Configuration File

The file config.c in the project directory allows the game developer to provide configuration options for some of the Pluto 6 software drivers. The configuration options are applied to the drivers on installation. In the example projects default configuration options are provided for the configurable drivers.

Pluto 6 Configurable Drivers

The following Pluto 6 drivers are configurable:

Driver | Configuration Information
Advanced Video Driver | Advanced Video Driver Configuration Data
Multiplexed Inputs Driver | MXI Configuration Data
Outputs Driver | Outputs Configuration Data
Serial Communications Drivers | Serial Communications Configuration Data
PIC18 Customer Security Device Driver | PIC18 Customer Security Device Configuration Data
E2ROM Device Driver | E2ROM Device Configuration Data
Vacuum Fluorescent Display Drivers | VFD Configuration Data
ATA Driver | ATA Configuration Data
Timers Driver | Timer Configuration Data
Stepper Motor Driver | Stepper Configuration Data
Touchscreen Driver | Touchscreen Controller Configuration
E2ROM Driver | E2ROM Configuration

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


devices.c

This file allows the game developer to specify which device drivers are loaded for a particular gaming application. The device list is read on system startup by the Device Manager and all listed device drivers are loaded.

For further information on device list entry definition refer to the Defining a Device List page.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


fpga.c

This file provides memory mappings for accessible registers in the Pluto 6 FPGA. The chip select settings for the Motorola ColdFire® are also contained in this file.

Warning: Changing the values of the chip select registers may stop the Pluto 6 control board from working so should not be attempted unless necessary.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


sysram.c

Variables declared in this file will be stored in non-volatile memory. Values assigned to the variables will be retained during system power down.

This section of memory is cleared on start-up when a change of identity or change of checksum is detected. This section is intended for variables whose values are not initialised on start-up and retain their values through a power down. Variables may be placed in this section only on a file by file basis by modifying the linker script.

The demonstration program contains a module called ‘sysram.c’. Any uninitialised variables defined in this file are located in the System RAM section of memory.

See the linker script file for further information.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


idram.c

This section of memory is cleared on start-up only when a change of program identity is detected. It is intended to hold variables whose values must be preserved through a software revision update. It is the responsibility of the game programmer to ensure that each game has a unique identity. The 32bit constant integer ‘MachineId’ holds the value, which identifies the software.

Variables may be placed in this section only on a file by file basis by modifying the linker script. The demonstration program contains a module called ‘idram.c’. Any uninitialised variables defined in this file are located in the Identity RAM section of memory.

See the linker script file for further information.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Demonstration Program

Pluto 6 Demonstration Program

Demonstration Program Documentation

The executable file, demo.s19, created from the demonstration program is on the Compact Flash Card supplied as part of the Pluto 6 Development Kit.

Component | Description
Demonstration Program Overview | An overview of the video demonstration project.

See Also

  • Remote PC Physical Setup
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Demonstration Software

Demonstration Program Overview

The standard demonstration program supplied with the Pluto 6 Development Kit allows the user to test the hardware functionality using the Heber software libraries. The program demonstrates the API functions that would typically be used in a reel based application.

Demonstration Program Operation

The demonstration program has two modes of operation:

  • Automated Mode - In this mode the software will enter a continuous loop displaying patterns on the lamp matrix, VFD, LEDS, open drain output LEDs, and transmitting characters over the serial ports. The software enters this mode on start up and will re-enter this mode when not being driven by the user.
  • Command Mode - In this mode the user can test the Pluto 6 functionality through a series of menus displayed on a remote PC. For information on how to set up a PC to use the demonstration program in Command Mode click here.

Demonstration Program Command Mode

Using menus displayed through a serial port on a remote PC the user can test the hardware functionality using the software APIs provided in the Pluto 6 Development Kit.

Set up the Pluto 6 as described in the Getting Started guide and connect it to a PC using a serial cable as described in the Remote PC Setup page. Press any key to enter the Main Menu.

Main Menu

The main menu provides the top level each of the drivers that are used in the demonstration software. To activate a menu item or access the driver sub-menu type the menu item into the HyperTerminal window and press Enter.

MAIN MENU | Top level menu
lamps | Lamps sub-menu
leds | LEDs sub-menu
inputs | Inputs sub-menu
outputs | Test outputs driver
reels | Reel driver sub-menu
serial | Serial driver sub-menu
audio | Streamed audio driver sub-menu
vfd1 | This test will scroll characters on VFD 1. To stop the test press any key.
csd | Customer security device driver sub-menu
e2rom | E2ROM driver sub-menu

Multiplexed Lamps Menu

The multiplexed lamps menu allows the user to test and set the Pluto 6 lamps driver.

MULTIPLEXED LAMPS MENU | Multiplexed lamp driver menu
strobe | Type strobe followed by enter and then press any key to advance through the lamp strobe lines. Type x to exit.
row | Type row followed by enter and then press any key to advance through the lamp rows. Type x to exit.
on | Type on followed by enter to set the lamps to the on state. This will clear any previous flash states set.
flash | Type flash followed by enter to set the lamps to the flash state. Follow this command with a strobe or row command to view the lamps flashing.
fastflash | Type fastflash followed by enter to set the lamps to the fast flash state. Follow this command with a strobe or row command to view the lamps fast flashing.
dim | Type dim followed by enter to dim the lamps. Follow this command with a strobe or row command to view the dimmed lamps.
restore | Type restore followed by enter to restore the lamps to their default state.
exit | Type exit followed by enter to return to the main menu.

Multiplexed LEDs Menu

The multiplexed LEDS menu allows the user to test and set the Pluto 6 LEDs driver.

MULTIPLEXED LEDS MENU | Multiplexed LEDs driver menu
digit | Type digit followed by enter and then press any key to advance through the digits. Type x to exit.
segment | Type segment followed by enter and then press any key to advance through the LED segments. Type x to exit.
dim | Type dim followed by enter to dim the LEDs. Follow this command with a digit or row segment to view the dimmed LEDs.
restore | Type restore followed by enter to restore the LEDs to their default state.
exit | Type exit followed by enter to return to the main menu.

Inputs Menu

The inputs menu allows the user to test the Pluto 6 inputs.

INPUTS | Inputs driver menu
inputs | Type inputs followed by enter and the state of the 32 Pluto 6 inputs will be displayed on the screen. The input readings are updated every 10ms. Press any key to exit.
pushbutton | Type pushbutton followed by enter and the state of the push button on the Pluto 6 control board will be displayed. Press the push button and the displayed state will change. Press any key to exit.
metersense | Type metersense followed by enter and the state of the meter sense circuit on the Pluto 6 control board will be displayed. If the state changes it will be displayed. Press any key to exit.
exit | Type exit followed by enter to return to the main menu.

Reel Menu

The reel menu allows the user to test the Pluto 6 reel driver using four reels. The driver for the demonstration software uses StarPoint RM161680 ramp tables. The reels are initialised when the reels sub-menu is entered.

REEL MENU | Reel driver menu
init | Type init followed by enter to re-initiaise the reels to their reference points.
step1 | Type step1 followed by enter to step reel 1 forward 1 step.
step2 | Type step2 followed by enter to step reel 2 forward 1 step.
step3 | Type step3 followed by enter to step reel 3 forward 1 step.
step3 | Type step3 followed by enter to step reel 3 forward 1 step.
step4 | Type step4 followed by enter to step reel 4 forward 1 step.
spin | Type spin followed by enter to spin all four reels.
skill | Type skill followed by enter to spin all four reels. Each time a key is pressed a reel will stop.
status | Type status followed by enter to display the number of tabs that have been missed and the number of times that the reel position has been corrected for each reel.
exit | Type exit followed by enter to return to the main menu.

UART Menu

The UART menu provides access to tests for the serial ports on the Pluto 6 control board with the exception of the ColdFire® serial channel 0 which is used for the menu display.

UARTS MENU | Serial driver menu
cfuart1 | Type cfuart1 followed by enter to enter the ColdFire® serial channel 1 sub-menu.
fpuart0 | Type fpuart0 followed by enter to enter the FPGA UART0 sub-menu.
fpuart1 | Type fpuart1 followed by enter to enter the FPGA UART1 sub-menu.
duart0 | Type duart0 followed by enter to enter the DUART0 sub-menu.
duart1 | Type duart1 followed by enter to enter the DUART1 sub-menu.
exit | Type exit followed by enter to return to the main menu.

UART Sub-Menu

The UART sub-menu allows the user to configure and test the Pluto 6 serial ports. The same options are available for all ports.

UART TEST MENUs | Each of menu has a title based on which serial port is being tested.
configure | Type configure followed by enter to configure the serial port. To select a configuration option type the option name followed by enter. This menu item allows the setting of Baud rate, Parity, Data bits and Stop bits.
route | Type route followed by enter route a particular UART to one of the output serial ports on the Pluto 6 control board. Type the route name and press enter.
transmit | Type transmit followed by enter transmit a character using the UART with the configuration settings and route previously specified.
receive | Type receive to receive a character. To perform this test a serial input device must be connected to the serial port to which the UART has been routed.
exit | Type exit followed by enter to return to the UARTS main menu.

Heber Sound File Audio Menu

The Heber Sound File (HSF) audio menu allows the user to test the Pluto 6 HSF audio driver. The HSF audio driver allows the user to play audio samples from the Compact Flash card supplied with the Pluto 6 Development Kit. Sample files have been converted with the ulawconv utility. Before displaying the HSF Audio menu the Compact Flash card is initialised.

HSF AUDIO MENU | Menu for the HSF audio driver.
dir | Type dir followed by enter to list the audio files in the /audio directory on the Compact Flash card.
setvol | Type setvol followed by enter to set the volume level on an audio channel. The level must be between 0 (silence) and 255 (maximum)
play | Type play followed by enter play a HSF sound sample. Enter the name of the sample to play (which must be a sample in the /audio directory on the Compact Flash card) and press enter. Type in the channel over which you wish to play the sample from the options displayed and press enter.
loop | Type loop followed by enter play looped a HSF sound sample. Enter the name of the sample to play (which must be a sample in the /audio directory on the Compact Flash card) and press enter. Type in the channel over which you wish to play the sample from the options displayed and press enter. Use the quiet menu option to silence the audio channel.
quiet | Type quiet followed by enter to silence an audio channel. To silence a channel type one of the options displayed and press enter.
exit | Type exit followed by enter to return to the main menu.

Customer Security Device Menu

The Customer Security Device menu allows the functionality provided by the PIC18 device on the Pluto 6 control board to be tested.

PIC MENU | Menu for the PIC CSD driver.
readrtc | Type readrtc followed by enter read the current Real Time Clock Value. The time will be displayed every second until a key is pressed.
setrtc | Type setrtc followed by enter to set Real Time Clock. You will be prompted to enter the year, month, date, hour and minute. Use numbers to enter the values.
readlog | Type readlog followed by enter to read the security log. You will be prompted to enter a log entry number (between 0-9) and the entry will be displayed.
clearlog | Type clearlog followed by enter to clear all of the security log entries.
percent | Type percent followed by enter to read the percentage key value.
stake | Type stake followed by enter to read the stake/prize key value.
dil1 | Type dil1 followed by enter to read DIL switch bank 1.
dil2 | Type dil2 followed by enter to read DIL switch bank 2.
revision | Type revision followed by enter to read the CSD revision number.
exit | Type exit followed by enter to return to the main menu.

E2ROM Device Menu

The E2ROM Device menu allows the user to write data to and read data from the E2ROM device optionally fitted to socket U7 on the Pluto 6 control board.

E2ROM MENU | Menu for the E2ROM driver.
read | Type read followed by enter. Enter a value for the offset from address 0x00 to read from and press enter. Enter a value for the number of bytes to read and press enter. The data read from the E2ROM device will be displayed.
write | Type write followed by enter. Enter a value for the offset from address 0x00 to write to and press enter. Enter a value for the number of bytes to write and press enter. Type the characters to be written to the E2ROM device and press enter. The data will be written to the E2ROM device at the offset address specified.
exit | Type exit followed by enter to return to the main menu.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Remote PC Setup

Remote PC Setup

Physical Connection

To access the demonstration program menu the Pluto 6 control board must be connected to a remote PC via a serial cable. To do this attach one of the ribbon cables with a 25-way D-Type connector supplied in the Development Kit to either connector DATAPORT (P22) on the Pluto 6 board, or if the Pluto 6 is mounted on the Evaluation board, the DATAPORT connector.

The D-Type connector at the other end of the ribbon cable should be fitted with the 25 to 9-Way D-Type converter supplied in the Pluto 6 Development Kit, and then connected to a serial port on the remote PC.

PC Software Setup

Launch HyperTerminal on the host PC (Start - Programs - Accessories - Communications - HyperTerminal).

Enter the name for your connection in the Name edit box and click OK.

Select the serial port that you have connected the serial ribbon cable to on your PC in the Connect Using box and click OK.

Set the following serial port configuration:

  • Bits per second: 9600
  • Ddata bits: 8
  • Parity: None
  • Stop bits: 1
  • Flow control: None

Click OK.

Open the Properites window in your HyperTerminal window (File - Properties).
Click the Settings tab.
Click the ASCII Setup button.

Check the Append line feeds to incoming line ends check box.
Click the OK button to close the ASCII setup window.
Click the OK button to close Properties window.

Power up the Pluto 6 board with the Compact Flash card containing the demonstration software fitted and a screen similar to the one above should be displayed.
Press any key to return to the menu system.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Demonstration Program

Pluto 6 Advance Dual Video Demonstration Program

Dual Video Demonstration Program Documentation

The image files used by the dual video demonstration project are included on the Compact Flash Card supplied as part of the Pluto 6 Development Kit. To run the dual video demonstration program copy the file vdemo.s19 from the dual video project directory to the Compact Flash card.

Component | Description
Dual Video Demonstration Program Overview | An overview of the Dual Video demonstration project.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Demonstration Program

Pluto 6 Dual Video Demonstration Program Overview

The Dual Video demonstration program supplied with the Pluto 6 Development Kit shows the use of the Calypso 32 Advanced Video driver in a dual screen setup and provides examples of techniques that are common to video gaming applications. Images used in the video demonstration are in 24 bit per pixel Windows® bitmap (.bmp) format and are loaded from Compact Flash card.

Note: Before you power up the Pluto 6 control board to run the video demonstration program, ensure the Compact Flash card is fitted in the CF SLOT, Calypso 32 Video Cards are fitted in both expansion slots, EXP 0 and EXP 1 on the Pluto 6 board, and monitors are attached to the Pluto 6 VGA output connectors, P24 and P25.

Program Operation

The demonstration program runs through an infinite loop calling separate functions, in which different sequences are run:

Start Up

On start up the following steps are performed:

  • The Compact Flash card where the images are stored is mounted.
  • The video cards are initialised.
  • At the beginning of each sequence the required background images are loaded into video memory.

Sequences

The program demonstrates double buffering, the use of multiple video layers.

See Also

  • Address Map
  • Interrupts
  • Dual Video Device Parameter
  • Dual Video Configuration Data
  • Font Loading functions
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Demonstration Program

Touchscreen Driver with Advanced Video Driver Overview

The Touchscreen demonstration program supplied with the Pluto 6 Development Kit shows the use of the Calypso 32 Advanced Video Driver in a touchscreen setup and provides examples of techniques that are common to video gaming applications (calibration, moving a sprite with the finger on screen).

The images used in the Touchscreen demonstration are compiled with program and follows the CALYPSO format.

Component | Description
Touchscreen Demonstration Program Overview | An overview of the Touchscreen demonstration project.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Demonstration Program

Program Operation

Start Up

On start up the following steps are performed:

  • Configuration of Advanced Video Driver
  • Video memory Set up
  • Loading of images into video memory
  • Selection of the Touhscreen Driver used according to an input switch
  • Configuration of the communication device affected to the touchscreen
  • Routing of the serial device to a port
  • Configuration of the touchscreen to be able to communicate with the serial device
  • Calibration of the touchscreen => 2 target sprites are used for this steps
    • First in the bottom left corner
    • Then in the top right corner
  • Call main loop to demonstrate the tracking of a finger around the screen.

Main Loops

The image of a card is used for this part. During the tracking finger demonstration, the following actions are performed:

  • Getting finger position on screen
  • Clearing sprite at old position
  • Displaying sprite at new position
  • Report position of the finger on screen and on debug serial port.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Boot Loader

Pluto 6 Boot Loader

The Pluto 6 Development Kit is supplied with the following demonstration programs:

  • A standard demonstration program
  • A dual video demonstration program

These demonstration programs are supplied on the included Compact Flash Card. The files are called:

  • demo.s19
  • vdemo.s19

The files are in Motorola S-Record format. The souce code for the three demonstration projects is supplied on the development kit CD-ROM.

A Boot Loader is used to load and execute the necessary demonstration program. This loader resides in the Boot Flash (fitted in socket U1 in the Pluto 6 control board) and is automatically executed when the Pluto 6 is powered up. The Boot Loader performs the following steps:

  • Auto-detects the Calypso 32 graphics card.
  • If the graphics card is detected then loads and executes vdemo.s19 from Compact Flash.
  • If the graphics card is not detected loads and executes demo.s19 from Compact Flash.
  • If there are any problems Pluto 6 will not execute any demonstration code. (Refer to the Boot Loader Troubleshooting Guide).

Boot Loader Documentation

Component | Description
Software Overview | A high level overview of the boot loader project.
Troubleshooting | A troubleshooting guide for the boot loader project.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Boot Loader Software Overview

The source code for the Boot Loader is located in the file game.c and is supplied with the Development Kit. This document provides a high level overview of each function in game.c that implements the Boot Loader. For further detail refer to the comments in the source code.

Boot Loader Functions

Function

void Game( )

Description

This function is automatically called once the Pluto 6 is powered up or reset. Previously it would call DemoFnc() (located in demo.c) to run a demonstration program. It now performs the following:

  • Initialises and mounts the Compact Flash card.
  • Uses function GraphicsCardDetected() to detect whether a Calypso 32 graphics card is fitted.
  • If a graphics card is fitted, use function ExecuteS19File() to execute file vdemo.s19.

If any of the above steps failed for any reason, an infinite loop will be entered.

If you wish to change the boot loader for your own purposes (for example, to load a .s19 with a different filename) it is recommended that you only alter this function. If changes are made to the boot loader the project must be re-built and the output .s19 file programming into a boot flash device. This device must then be fitted into socket U1 on the Pluto 6 control board.

Function

BYTE GraphicsCardDetected( )

Description

This function detects whether a Calypso 32 graphics card is fitted. The function will return 1 if there is a graphics card, and 0 if there is not.

Function

BYTE ExecuteS19File( BYTE *filename )

Description

This function performs the following steps:

  • Opens the .s19 file specified in filename (e.g. vdemo.s19).
  • Uses function LoadS19Sector( ) to load the first sector from the .s19 file.
  • Uses function AnalyseS19File( ) to load the rest of the .s19 file into memory.
  • Closes the .s19 file.
  • Sets the Stack Pointer (this address is found in the first address loaded from the .s19 file).
  • Jumps to the beginning of the .s19 code (this address is found in the second address loaded from the .s19 file).

Function

BYTE AnalyseS19File( BOOTLOADER *bootLoader )

Description

This function loads the entire .s19 file into memory one byte at a time. Once written, each byte is read back and compared against a checksum to ensure that the .s19 file is not corrupted. If there is a mismatch then this function will fail and return 1.

Function

LONG NibblesToNum( BOOTLOADER *bootLoader, LONG numBytes )

Description

This function reads numBytes bytes from the .s19 file and converts them to a LONG value.
For example, if the .s19 file contained the following text: “4F5E”, NibblesToNum( &bootLoader, 4 ) would return 0x4f5e.

Function

BYTE GetS19FileByte( BOOTLOADER *bootLoader )

Description

This function returns a single byte from the .s19 file. Data is actually read from the .s19 file one sector (512 bytes) at a time and this is buffered in the BOOTLOADER structure. If the buffer is empty then this function will call LoadS19Sector( ) to load another sector.

Function

BYTE LoadS19Sector( BOOTLOADER *bootLoader )

Description

This loads a single sector (512 bytes) from the .s19 file and buffers it in the BOOTLOADER structure.

Function

BYTE EndOfS19File( BOOTLOADER *bootLoader )

Description

This function returns 1 if the end of the .s19 file has been reached or 0 if the end of the file has not been reached.

Boot Loader Data Structures

Structure BOOTLOADER

Description

The following data structure is used by the boot loader:

typedef struct bootloader
{
    FILE_DESCRIPTOR file;			/* File pointer */
    LONG firstAddress;			/* First address in S19 file */
    ULONG	s19FilePos;			/* Current file offset */
    /* Buffer containing 1 sector of S19 file data */
    BYTE	fileBuffer[SECTOR_BYTES];
    LONG	fileBufferPos;			/* Position in file buffer */
} BOOTLOADER;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Boot Loader Troubleshooting Guide

This section lists a number of reasons why a demonstration program does not run on Pluto 6 after power is turned on and offers solutions to these problems.

Cause of Problem | Solution
No Compact Flash card. | For the boot loader to work a Compact Flash card formatted with a FAT32 file system and containing the relevant .s19 files must be fitted into the CF SLOT on the Pluto 6 controller board.
You have not waited long enough. | Depending on the size of the .s19 file on the Compact Flash card it can take several seconds to download and execute the file.
The required file is not present. | When a graphics card is present the file vdemo.s19 must exist. If a graphics card is not present the file demo.s19 must exist. These files must be located in the root directory of the Compact Flash card.
A graphics card is connected but the non-video demo is executed. | The .s19 file on the Compact Flash card may be corrupted. Try re-building the demonstration project that you wish to load and resaving it on the Compact Flash card.
You have not waited long enough. | There may be a problem with your video card. For debugging purposes rename vdemo.s19 to demo.s19 and check that when executing the video demo that the graphics card is working properly.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Software Getting Started

Converting Your Project to use the Dual Video Hardware Library

A Dual Video Driver has been developed to enable two Calypso 32 Cards to be used with Pluto 6 to provide Dual Video. The Dual Video driver is contained within the Advanced Video Driver.

To achieve Dual Video capability, the Pluto 6 Hardware Library has been modified to allow the use of two Calypso 32 cards. Backwards compatibility is preserved, but some changes are required to your game if you are using Version 15 of the Hardware Library. This section documents the changes needed to your existing game when using the Dual Video Hardware Library, from version 15 onwards.

1. In fpga.h:

  • Find the comment:
    • XCRA Control register A
  • Ensure the following four definitions are present:
    •  #define SFX_ENABLE  0x80 /*enable sound*/
 #define IRQ_ENABLE  0x40 /*enable FPGA interrupts
 #define MPX_ENABLE  0x20 /*multiplex drivers enable
 #define SYNC_ENABLE 0x10 /*dual video: synchronise second
  video board to first video board*/
  • Find the comment:
    • Calypso 32 Base Address Definitions
  • Ensure the following three definitions are present:
    •  #define CALYPSO32PLUS_BASE  (LONG)(0x30000000)			/*CS3*/
 #define CALYPSO32DUAL0_BASE (LONG)(0x30000000)			/*CS3*/
 #define CALYPSO32DUAL1_BASE (LONG)(0x30000000)+0x4000000	/*CS3+64M*/

2. In fpga.c:

  • Find the comment:
    • XCRA Control register A
  • Ensure the following four definitions are present:
    • UBYTE Sfxenable=SFX_ENABLE;
UBYTE Irqenable=IRQ_ENABLE;
UBYTE Mpxenable=MPX_ENABLE;
UBYTE Syncenable=SYNC_ENABLE;

3. In config.c:

  • At the top of the file, find where the interrupt lists are defined and after
    void (*IntVideoLst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};

  • Ensure the following two lines are present:
    • void (*IntVideo0Lst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntVideo1Lst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
  • At the bottom of the file, find where the Calypso 32 Advanced Video Configuration is defined.
  • Ensure that the following three (and no other) configurations are present:
    • const CALYPSO32PLUSCFG Calypso32PlusCfg[]=
      {
      {Calypso800x600,palette,CALYPS032PLUS_BASE,CalypsoPlusISR,
IntVideoLst,CalypsoPlusISR1ms},
      {0}
       };

    const CALYPSO32PLUSCFG Calypso32Dual0Cfg[]=
      {
      {Calypso800x600,palette,CALYPSO32DUAL0_BASE,Calypso0ISR,
IntVideo0Lst,Calypso0ISR1ms},
      {0}
      };

    const CALYPSO32PLUSCFG Calypso32Dual1Cfg[]=
       {
       {Calypso800x600,palette,CALYPSO32DUAL1_BASE,Calypso1ISR,
IntVideo1Lst,Calypso1ISR1ms},
       {0}
       };
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Software Modules

Pluto 6 Software Modules

The Pluto 6 control board is supplied with software in compiled library format that can be read by the GNU linker. The software is organised in discreet software modules, each of which provides a specific type of functionality to the game developer. One compiled library is supplied for each software module.

In addition to the compiled libraries, the source code is supplied for two of the software modules to provide a template for developers to create specialised drivers and gaming applications.

Module | Description
Hardware Abstraction Module | Provides a software interface to the Pluto 6 hardware, low level device drivers, board initialisation and process management software in compiled library format.
Standard Peripherals Module | Provides higher level drivers for many common peripheral devices which access the hardware through the Hardware Abstraction Module. The software is supplied in compiled library format.
Customer Peripherals Module | Provides examples of higher level peripheral drivers that can be used as a starting point for game developers to create specialised drivers. The source code is supplied for this module.
Standard Interface Module | Provides higher level drivers that are not hardware specific and can address one or more hardware devices. Hardware is accessed through the Hardware Abstraction Module, or indirectly through the Peripherals Modules. The software is supplied in compiled library format.

See Also

  • GNU Compiler
  • Software Conventions
  • Software Architecture
  • Source File Types
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Hardware Abstraction Module

This module contains the following:

  • System initialisation code
  • Process management code
  • Low level drivers that allow direct access to hardware on the Pluto 6 control board.

The software Application Programming Interface (API) in hardware abstraction module gives the games developer access to the Pluto 6 hardware functionality without having to directly address the hardware.

Hardware Abstraction Module Components

Component | Description
Advanced Video Driver | The Advanced Video Driver allows the use of advanced features of the Calypso 32 graphics driver software, including Dual Video functionality.
Multiplex Driver | The Multiplex Driver allows the control the multiplexed lamps and seven segment displays on the Pluto 6 control board.
Multiplexed Inputs Driver | The Multiplexed Inputs Driver allows the control of Pluto 6 system inputs.
Outputs Driver | The Outputs Driver allows the control of the Pluto 6 system outputs.
Serial Communications Driver | The Serial Communications Driver allows access to the services of multiple serial devices available on the Pluto 6 control board.
PIC18 Driver | The PIC18 Driver provides functions to access data on the PIC18 Customer Security Device.
M-Bus (I²C) Driver | The M-Bus Driver provides an I²C interface on the Pluto 6 control board.
Vacuum Fluorescent Display (VFD) Driver | The VFD Driver provides low level functions for addressing vacuum fluorescent displays.
ATA Driver | The ATA Driver provides the low level functions to access an ATA hard disk or compact flash card.
Device Manager | The Device Manager provides the functionality for manipulating device drivers.
Entry Module | The Entry module provides the low-level initialisation of the Pluto 6 hardware.
Interrupt Module | The Interrupt Module provides functionality to allow the user to install functions that will run triggered by system interrupts.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Advanced Video Driver

The Advanced Video Driver module provides an Application Programming Interface to allow the development of video based games using the Calypso 32 video card.

Pluto 6 boards, (with part number, 01-17802), have dual video capability and can be fitted with two Calypso 32 video cards. The two video cards are mapped to different address ranges, which allows each board to be accessed independently. A single interrupt line is shared by both boards. Separate VGA video output connectors are provided on the Pluto 6 board - P24 and P25.

The Advanced Video Driver also enables more features of the Calypso 32 add on board to be utilised. Features that the Advanced Video Driver enable include: Alpha blending, Unicode character support and animation sequences.

API Functions

The following API functions are associated with this module:

Function | Description
CalypsoInitDisplayMode | Initialises the video display resolution.
CalypsoVideoOn | Turns on video output.
CalypsoVideoOff | Turns off video output.
CalypsoGetVsync | Returns vertical sync.
CalypsoSetVideoMemory | Block fill video memory.
CalypsoInitLayer | Initialises Cremson Display Layer.
CalypsoEnableLayer | Makes the Display Layer visible.
CalypsoDisableLayer | Makes the Display Layer invisible.
CalypsoScrollLayerX | Scrolls the Display Layer in x-direction with wrap around.
CalypsoScrollLayerY | Scrolls the Display Layer in y-direction with wrap around.
CalypsoClearLayer | Clears Display Layer to BLACK (colour 0x0000).
CalypsoFillLayer | Fills Display Layer with 8 or 16 bit colour.
CalypsoSetWindowLayer | Sets the Window Layer parameters.
CalypsoSetFrameRate | Sets maximum frame update rate.
CalypsoEnableDoubleBuffer | Enables double buffering.
CalypsoDisableDoubleBuffer | Disables double buffering.
CalypsoSetDoubleBufferFrame | Allows manual selection of the currently displayed double buffer frame. (BASE and MIDDLE layers).
CalypsoGetDoubleBufferFrame | Gets the current non-displayed double buffer frame.
CalypsoSetFrameNumber | Initialises the Frame Number.
CalypsoFrameAdvance | Advances to the next frame on next vertical interrupt.
CalypsoGetFrameNumber | Reads the current Frame Number.
CalypsoScreenPartitionX | Sets screen X position of partition between left layer and right layer.
CalypsoAlphaBlend | Enables/disables the console layer with Alpha Blending.
CalypsoSetBlendRatio | Sets the blend ratio for Alpha Blending between Console Layer and Base/Middle/Window Layers.
CalypsoLoadPalette | Loads the palette table.
CalypsoGetPaletteEntry | Gets the palette entry from palette table.
CalypsoSetPaletteEntry | Sets the palette entry in a palette table.
CalypsoLoadImage | Loads the image from system to video memory.
CalypsoLoadImageLayer | Loads image from system to specified Display Layer in video memory.
CalypsoLoadImageConvert8to16 | Loads image from system to video memory with 8-bit to 16-bit colour conversion.
CalypsoLoadImageLayerConvert8to16 | Loads image from system to Display Layer with 8-bit to 16-bit colour conversion.
CalypsoCreateMask | Creates a transparency mask in video memory for a loaded .bmp file.
CalypsoLoadSprite | Loads image from system to video memory, then creates and loads image mask to next video memory address.
CalypsoPutSprite | Blits sprite from undisplayed video memory to Display Layer.
CalypsoSaveSprite | Save Block (sprite) from Display Layer to undisplayed video memory.
CalypsoClearSprite | Clears Block (sprite) in Display Layer.
CalypsoFillSprite | Fills Block (sprite) in Display Layer with colour value.
CalypsoSetAsciiFont | Sets the current ASCII text font.
CalypsoSetTextColor | Sets the current text colour.
CalypsoSetTextPosition | Sets Display Layer current text writing position.
CalypsoGetTextPositionX | Gets current text writing position x coordinate for layer.
CalypsoPutChar | Writes text character to Display Layer at current layer writing position.
CalypsoPutStr | Writes text string to Display Layer at current layer writing position.
CalypsoSetUnicodeFont | Assigns Unicode font to code page.
CalypsoGetUnicodeFont | Returns the Unicode Font assigned to Unicode code page.
CalypsoPutUnicodeChar | Writes Unicode character to display layer.
CalypsoPutUnicodeStr | Writes Unicode string to display layer.
CalypsoDefineAnimation | Defines in full an animation sequence.
CalypsoAddToAnimationList | Adds an animation to the list of currently active animations.
CalypsoRemoveFromAnimationList | Removes an animation from the list of currently active animations.
CalypsoClearAnimationList | Removes all animations from the Animation List.
CalypsoStartAnimation | Starts an animation.
CalypsoStopAnimation | Stops an animation.
CalypsoPauseAnimation | Pauses an animation.
CalypsoStepAnimation | Single step an animation.
CalypsoPoint | Draws a pixel to the current Display Layer.
CalypsoLine | Draws a line to the current Display Layer.
CalypsoCircle | Draws a circle to the current Display Layer.
CalypsoGetDisplayHsize | Displays screen horizontal size in pixels.
CalypsoGetDisplayVsize | Displays screen vertical size in lines.
CalypsoSyncLockEnable | Synchronise the Display Scan of the second video board to the first video board.
CalypsoSetLineProperties | Sets line width.
CalypsoAdvanceLine | Draws line to display layer between points A and B.
CalypsoAdvanceRectangle | Draws an empty rectangle on the screen.
CalypsoAdvanceSetLineAntiAlias | Turns on anti-aliasing when using the advance line drawing functions.
CalypsoAdvanceClearLineAntiAlias | Turns off anti-aliasing when using the advance line drawing functions.

See Also

  • Calypso 32 Performance Limitations
  • Calypso 32 Colour Modes
  • Calypso 32 Transparency and Overlay Transparency
  • Calypso 32 Video Layer Architecture
  • Transparency Parameter
  • Advanced Video Driver Configuration Data
  • Display List Handling
  • Layer-centric Commands
  • Colour Depth Issues
  • Alpha Blending
  • Unicode Character Support
  • Animation Sequence
  • Video/Advanced Video Driver Operational Comparison
  • Address Map
  • Interrupts
  • Dual Video Device Parameters
  • Dual Video Configuration Data
  • Font Loading functions
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Init Display Mode API Function

Advanced Video Driver

API Function

void CalypsoInitDisplayMode(const DEVICE* dev, const WORD *reg_table);

Description

Initialise video display resolution.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
reg_table | Permitted Values: Calypso1024x768 Calypso800x600 Calypso640x480

Return Value

None.

Code Example

CalypsoInitDisplayMode(&Calypso32PlusDevice, Calypso800x600);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Video On API Function

Advanced Video Driver

API Function

void CalypsoVideoOn(const DEVICE* dev);

Description

Turn on video output.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

None.

Code Example

CalypsoVideoOn(&Calypso32PlusDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Video Off API Function

Advanced Video Driver

API Function

void CalypsoVideoOff(const DEVICE* dev);

Description

Turn off video output.

Remarks

Preserves layer enable settings.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

None.

Code Example

CalypsoVideoOff(&Calypso32PlusDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get VsyncAPI Function

Advanced Video Driver

API Function

UBYTE CalypsoGetVsync(const DEVICE* dev);

Description

Returns vertical sync.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

Returns TRUE if vertical refresh is in progress.

Code Example

if (CalypsoGetVsync(&Calypso32PlusDevice))

  /* do something */
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Video Memory API Function

Advanced Video Driver

API Function

ULONG CalypsoSetVideoMemory(const DEVICE* dev, LONG video_addr, LONG size_bytes, BYTE color_mode, UWORD color);

Description

Block fill video memory.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
video_addr | Start address (offset from start of video memory).
size_bytes | Size in bytes to set – must be multiple of 32 bytes.
color_mode | DIRECT_COLOR (16 bit). INDIRECT_COLOR (8 bit).
color | colour value (8 or 16 bit).

Return Value

Next address after block fill.

Code Example

CalypsoSetVideoMemory(&Calypso32PlusDevice, 0, 0x1000000, INDIRECT_COLOR, BLUE);

CalypsoSetVideoMemory(&Calypso32PlusDevice, 0, 0x1000000, DIRECT_COLOR, 0x7FFF);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Init Layer API Function

Advanced Video Driver

API Function

LONG CalypsoInitLayer(const DEVICE* dev, LONG layer_select, BYTE color_mode, BYTE buffer_mode, WORD transparent_color, WORD width_pixels, WORD height, LONG start_address);

Description

Initialise Cremson Display Layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
color_mode | Display Layer colour mode: DIRECT_COLOR - 16 bit colour INDIRECT_COLOR - 8 bit colour
buffer_mode | Display Layer buffer mode: SINGLEBUFFER single buffer mode DOUBLEBUFFER double buffer mode This parameter is ignored for console and window layers, which are not double buffered.
transparent_color | transparent colour (8 or 16 bit) Display Layer transparent colour. Any pixel in the layer with this colour is transparent: lower priority layers are visible at this point. The priority order of Display Layers is: console > middle > base The window layer is not transparent.
width_pixels | Mandatory: width_pixels >= display horizontal size width_pixels must be multiple of 64
height | Display Layer height in lines.
start_address | Display Layer start address (offset from start of video memory).

Return Value

Returns next free start address.
This allows sequential mapping of video memory to Display Layers.

Code Example

/* Initialise BASE  then MIDDLE  then CONSOLE Layers */
base_start    = 0;

middle_start = CalypsoInitLayer(&Calypso32PlusDevice, BL_LAYER,
        DIRECT_COLOR, DOUBLEBUFFER, 0x0000, H_SIZE, V_SIZE, base_start);

console_start  = CalypsoInitLayer(&Calypso32PlusDevice, ML_LAYER,
        INDIRECT_COLOR, DOUBLEBUFFER, BLACK, H_SIZE, V_SIZE, middle_start);

offscreen_start  = CalypsoInitLayer(&Calypso32PlusDevice, C_LAYER,
        INDIRECT_COLOR, SINGLEBUFFER, BLACK, H_SIZE, V_SIZE, console_start);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Enable Layer API Function

Advanced Video Driver

API Function

void CalypsoEnableLayer(const DEVICE* dev, UBYTE select);

Description

Enable (make visible) Display Layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
select | Select layer: BASE_SELECT MIDDLE_SELECT CONSOLE_SELECT WINDOW_SELECT ALL_SELECT

Return Value

None.

Code Example

/* Make base layer visible */
CalypsoEnableLayer(&Calypso32PlusDevice, BASE_SELECT);
/* Make base  and middle layers visible */
CalypsoEnableLayer(&Calypso32PlusDevice, BASE_SELECT | MIDDLE_SELECT);
/* Make all layers visible */
CalypsoEnableLayer(&Calypso32PlusDevice, ALL_SELECT);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Disable Layer API Function

Advanced Video Driver

API Function

void CalypsoDisableLayer(const DEVICE* dev, UBYTE select);

Description

Disable (make invisible) Display Layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
select | Select layer: BASE_SELECT MIDDLE_SELECT CONSOLE_SELECT WINDOW_SELECT ALL_SELECT

Return Value

None.

Code Example

/* make console layer invisible */
CalypsoDisableLayer(&Calypso32PlusDevice, CONSOLE_SELECT);
/* make base and middle layers invisible */
CalypsoDisableLayer(&Calypso32PlusDevice, BASE_SELECT | MIDDLE_SELECT);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Scroll Layer X API Function

Advanced Video Driver

API Function

void CalypsoScrollLayerX(const DEVICE* dev, LONG layer_select, ULONG offset);

Description

Scroll Display Layer in x-direction with wrap around.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
offset | x-offset in pixels between top left of screen and start address of Display Layer.

Return Value

None.

Code Example

/* Continuous scroll at one pixel every 10ms */

while(1)
{
    CalypsoScrollLayerX(&Calypso32PlusDevice, C_LAYER,  x% H_SIZE);
    Wait(1);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Scroll Layer Y API Function

Advanced Video Driver

API Function

void CalypsoScrollLayerY(const DEVICE* dev, LONG layer_select, ULONG offset);

Description

Scroll Display Layer in y-direction with wrap around.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
offset | y-offset in lines between top left of screen and start address of Display Layer.

Return Value

None.

Code Example

/* Continuous scroll at one line per 10ms */

while(1)
{
    CalypsoScrollLayerY(&Calypso32PlusDevice, C_LAYER,  y% V_SIZE);
    Wait(1);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Clear Layer API Function

Advanced Video Driver

API Function

WORD CalypsoClearLayer(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame);

Description

Clear Display Layer to BLACK (colour 0x0000).

Remarks

Wait for this command to be completed before making any further video API calls.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame This parameter is ignored for console and window layers, which are not double buffered.

Return Value

None.

Code Example

/* Clear both double buffer frames of Base Left Layer */

CalypsoClearLayer(&Calypso32PlusDevice, BL_LAYER,  DOUBLEBUFFER_FRAME0);
CalypsoClearLayer(&Calypso32PlusDevice, BL_LAYER,  DOUBLEBUFFER_FRAME1);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Fill Layer API Function

Advanced Video Driver

API Function

WORD CalypsoFillLayer(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, UWORD color, UBYTE mode);

Description

Fill Display Layer with 8 or 16 bit colour.

Remarks

Wait for this command to be completed before making any further video API calls.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame. This parameter is ignored for console and window layers, which are not double buffered.
color | Fill colour. The colour depth (8-bit or 16-bit) should match the Display Layer colour depth.
mode | Fill mode: BLT_COPY - overwrite current pixels BLT_AND - logical AND with current pixels BLT_OR - logical OR with current pixels

Return Value

Return 0 if success.
Return 1 if fails.

Code Example

/* Fill console layer (8-bit) with RED colour */
CalypsoFillLayer(&Calypso32PlusDevice, C_LAYER, 0,  RED, BLT_COPY);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Window Layer API Function

Advanced Video Driver

API Function

void CalypsoSetWindowLayer(const DEVICE* dev, WORD x_position, WORD y_position, WORD width, WORD height);

Description

Set Window Layer parameters.
The Base, Middle and Console display Layers are full screen.
The Window Display layer is different: its screen size and position can be controlled.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
x_position | x position in pixels from screen left.
y_position | y position in lines from screen top.
width | window width in pixels.
height | window height in lines.

Return Value

None.

Code Example

/* 320x240 pixel window, top left at screen position x=50, y= 100 */
CalypsoSetWindowLayer(&Calypso32PlusDevice, 50, 100, 320, 240);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Frame Rate API Function

Advanced Video Driver

API Function

void CalypsoSetFrameRate(const DEVICE* dev, BYTE rate);

Description

Set maximum frame update rate. When using double-buffering, the display output flips between the two double-buffer frames at this rate. This is the maximum frame rate: frame update will be delayed if display list command execution has not finished.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
rate | Frame rate in Hz: FRAME_60HZ FRAME_30HZ FRAME_20HZ FRAME_15HZ FRAME_12HZ FRAME_10HZ FRAME_5HZ FRAME_3HZ FRAME_2HZ FRAME_1HZ FRAME_0HZ - manually advance frames using CalypsoFrameAdvance( )

Return Value

None.

Code Example

CalypsoSetFrameRate(&Calypso32PlusDevice, FRAME_60HZ);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Enable Double Buffer API Function

Advanced Video Driver

API Function

void CalypsoEnableDoubleBuffer(const DEVICE* dev);

Description

Enable double buffering. When double buffering is enabled, the Base Layer and Middle Layers will toggle the display output between their two double buffer frames at the frame rate set by CalypsoSetFrameRate( ).

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

None.

Code Example

CalypsoSetFrameRate(&Calypso32PlusDevice, FRAME_30HZ);

CalypsoEnableDoubleBuffer(&Calypso32PlusDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Disable Double Buffer API Function

Advanced Video Driver

API Function

void CalypsoDisableDoubleBuffer(const DEVICE* dev);

Description

Disable double buffering.

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

None.

Code Example

CalypsoDisableDoubleBuffer(&Calypso32PlusDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Double Buffer Frame API Function

Advanced Video Driver

API Function

void CalypsoSetDoubleBufferFrame(const DEVICE* dev, BYTE frame);

Description

When double buffering is enabled, flipping between two display frames is automatic. This function allows manual selection of the currently displayed double buffer frame. (BASE and MIDDLE layers).

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame

Return Value

None.

Code Example

SetDoubleBufferFrame(&Calypso32PlusDevice, DOUBLEBUFFER_FRAME0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Double Buffer API Function

Advanced Video Driver

API Function

BYTE CalypsoGetDoubleBufferFrame(const DEVICE* dev);

Description

Get the current non-displayed double buffer frame.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

0 - double buffer frame 0.
1 - double buffer frame 1.

Code Example

static BYTE WaitNFrames(const DEVICE* calypso32device, UBYTE nframes)
{
            UBYTE i;
            WORD frame_number;

            for(i = 0; i < nframes; i++)
            {
                        frame_number = CalypsoGetFrameNumber(calypso32device);

                        while (frame_number==CalypsoGetFrameNumber(calypso32device)) ;
            }

            return(CalypsoGetDoubleBufferFrame(calypso32device));
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Frame No. API Function

Advanced Video Driver

API Function

void CalypsoSetFrameNumber(const DEVICE* dev, WORD n);

Description

Initialise Frame Number.
The Frame Number is a 16 bit counter that is incremented on every vertical display frame.
This counter can be used for timing and sequencing display events.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
n | Frame number.

Return Value

None.

Code Example

/* clear frame number counter */
CalypsoSetFrameNumber(&Calypso32PlusDevice, 0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Frame Advance API Function

Advanced Video Driver

API Function

void CalypsoFrameAdvance(const DEVICE* dev)

Description

Advance to next frame on next vertical interrupt.
Used for advancing frames under software control when frame rate set to 0HZ.

Remarks

The CalypsoFrameAdvance API function relates to the CalypsoEnableDoubleBuffer() API function. This must be enabled in order to use the CalypsoFrameAdvance function.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

None.

Code Example

/* animation */

while(1)
{
    CalypsoFrameAdvance(&Calypso32PlusDevice);

    /* wait for next frame */
    frame_number = CalypsoGetFrameNumber(&Calypso32PlusDevice);

    while (frame_number==CalypsoGetFrameNumber(&Calypso32PlusDevice));
    /* clear sprites*/
    /* update sprite xy positions */
    /* draw sprites */
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Frame No. API Function

Advanced Video Driver

API Function

WORD CalypsoGetFrameNumber(const DEVICE* dev);

Description

Read the current Frame Number.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

Current Frame Number value (16 bit counter).

Code Example

CalypsoSetFrameRate(&Calypso32PlusDevice, FRAME_30HZ);
CalypsoSetFrameNumber(&Calypso32PlusDevice, 0);

/* Wait for 30 frames = 1 second*/
while(CalypsoGetFrameNumber(&Calypso32PlusDevice)  < 30)
    ;

/* do something */
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Screen Partition X API Function

Advanced Video Driver

API Function

void CalypsoScreenPartitionX(const DEVICE* dev, WORD partition_xpos);

Description

Set screen X position of partition between left layer and right layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
partition_xpos | position in pixels from left of screen to partition.

Return Value

None.

Code Example

/* Left 25 % of screen: Base Left Layer	Right 75 % of screen: Base Right Layer */
CalypsoEnableLayer(&Calypso32PlusDevice, BASE_ENABLE);
CalypsoScreenPartitionX(&Calypso32PlusDevice, 0.25 * H_SIZE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Alpha Blend API Function

Advanced Video Driver

API Function

void CalypsoAlphaBlend(const DEVICE* dev, BYTE enable)

Description

Enable /disabling console layer alpha blending.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
enable | 0 - disable. 1 - enable.

Return Value

None.

Code Example

/* force the sripte to be half transaparent at start up */
blendratio=7;
CalypsoAlphaBlend(&Calypso32PlusDevice, ENABLE);
CalypsoSetBlendRatio(&Calypso32PlusDevice, blendratio,0);

/* play with ratio */
while(1)
{
            while( (ch = RxChar(&SerialDevice,0))<0);
            if(ch == '+')
            {
                        if(blendratio<15)
                        {
                                    blendratio++;
                        }
            }

            if(ch == '-')
            {
                        if(blendratio>0)
                        {
                                    blendratio--;
                        }
           }
           CalypsoSetBlendRatio(&Calypso32PlusDevice, blendratio,0);

}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Blend Ratio API Function

Advanced Video Driver

API Function

void CalypsoSetBlendRatio(const DEVICE* dev, BYTE blend_ratio, BYTE select);

Description

Set blend ratio for Alpha Blending between Console Layer and Base/Middle/Window Layers.
Alpha blending is useful for semi-transparency and fade effects.

Remarks

Alpha Blending works slightly differently for 8-bit colour and 16-bit colour layer.

Console Layer 8- bit Color:
Alpha blending is enabled depending on console palette table entries.
palette table entry bit 15 = 0 - pixels of this colour not alpha blended.
palette table entry bit 15 = 1 - pixel of this colour alpha blended.

Console Layer 16-bit Color:
Alpha blending is enabled on a pixel by pixel basis.
pixel bit 15 = 0 - pixel not alpha blended.
pixel bit 15 = 1 - pixel alpha blended.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
blend_ratio | blend ratio in 16 steps: 0 ( 0/15 Console Layer, 15/15 Other Layers) to 15 (15/15 Console Layer, 0/15 Other Layers)
select | 0 - blend ratio as above. 1 - blend ratio reversed from above.

Return Value

None.

Code Example

CalypsoAlphaBlend(&Calypso32PlusDevice, ENABLE);

for (i=15;  i>=0;  i--)
{
    /* slowly fade out console layer */
    CalypsoSetBlendRatio(&Calypso32PlusDevice, i, 0);
    Wait(10);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Palette API Function

Advanced Video Driver

API Function

void CalypsoLoadPalette(const DEVICE* dev, UBYTE palette_select, const PALETTE_RGB *pal_table);

Description

Load palette table.

Remarks

Palette source files can be generated from Image Alchemy™ format palette files using Heber utility palconv.exe.

This will produce a source file palette_name.c containing a converted palette table. This table is declared as an array of palette entry structures:

const PALETTE_RGB	 palette_name[256] = { 256 palette entry values…  };

Where the palette entry type PALETTE_RGB is:

typedef	struct palette_rgb
{
    /* 1= enable alpha blending for this colour (console layer only)*/
    UBYTE	alpha;
    UBYTE	red;		/* red value */
    UBYTE	green; 		/* green value */
    UBYTE	blue; 		/* rblue value */
} PALETTE_RGB;

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
palette_select | MIDDLE_BASE_LAYER_PALETTE - middle/base layer palette. CONSOLE_LAYER_PALETTE - console layer palette.
palette_table | pointer to palette table.

Return Value

None.

Code Example

/* load palettes */
CalypsoLoadPalette(&Calypso32PlusDevice, MIDDLE_BASE_LAYER_PALETTE, stdpalette);
CalypsoLoadPalette(&Calypso32PlusDevice, CONSOLE_LAYER_PALETTE, stdpalette);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Palette Entry API Function

Advanced Video Driver

API Function

void CalypsoGetPaletteEntry(const DEVICE* dev, UBYTE palette_select, UBYTE entry, PALETTE_RGB *rgb);

Description

Get palette entry from palette table.

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
palette_select | MIDDLE_BASE_LAYER_PALETTE - middle/base layer palette. CONSOLE_LAYER_PALETTE - console layer palette.
entry | Palette table entry 0-255.
rgb | Palette value structure.

Return Value

None.

Code Example

/* read value of colour 100 */
PALETTE_RGB rgb;
BYTE alpha, red, green, blue;

CalypsoGetPaletteEntry (&Calypso32PlusDevice, CONSOLE_LAYER_PALETTE, 100, &rgb);
alpha=rgb.alpha;
red=rgb.red;
green=rgb.green;
blue=rgb.blue;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Palette Entry API Function

Advanced Video Driver

API Function

void CalypsoSetPaletteEntry(const DEVICE* dev, UBYTE palette_select, UBYTE entry, PALETTE_RGB *col);

Description

Set palette entry in a palette table.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
palette_select | MIDDLE_BASE_LAYER_PALETTE - middle/base layer palette. CONSOLE_LAYER_PALETTE - console layer palette.
entry | Palette table entry 0-255.
rgb | Palette value structure.

Return Value

None.

Code Example

/* set value of colour 32 */
PALETTE_RGB rgb;

rgb.alpha = 1;    /* enable alpha blending for colour 32 */
rgb.red = 0xFF;   /* very red colour */
rgb.green =0x11 ;
rgb.blue = 0x11;

CalypsoSetPaletteEntry (&Calypso32PlusDevice, CONSOLE_LAYER_PALETTE, 32, &rgb);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Image API Function

Advanced Video Driver

API Function

LONG CalypsoLoadImage(const DEVICE* dev, LONG video_addr, const CALYPSOIMAGE *image);

Description

Load image from system to video memory.

Remarks

Works identically for 8 or 16 bit images.

Image width MUST be an even number.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Note: This API function is provided for compatibility with Pluto 5/Calypso 16. This API function allows image loading from system memory. In general, Pluto 6/Calypso 32 will not use this function but will load images in .bmp bitmap format from a Compact Flash card.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
video_addr | Display Layer start address (offset from start of video memory).
image | Pointer to image structure.

Return Value

Next free address.

Code Example

/* demo.c */
extern const CALYPSOIMAGE bgnd;
LONG next_video_memory address;

/* load background image to start of video memory */

next_video_memory address  = CalypsoLoadImage (&Calypso32PlusDevice, 0, &bgnd);

/* bgnd.c - generated by imagconv */
#include	"hardware.h"

#define SIZE_BYTES		0x00079e00
#define COLOR8		1
#define PALETTE_SIZE  	256
#define WIDTH		 	832
#define HEIGHT		 600
static const PALETTE_RGB palette[] =
{
    {0x80,0x00,0x00,0x00},	/* Col 0 */

    /* more palette data... */

    {0x80,0x00,0x00,0x00},	/* Col 255 */
    {0,0,0,0}
};

static const WORD data[] =
{
    0x1111,

    /* more image data... */

    0
}
;

const CALYPSOIMAGE bgnd =
{
    (ULONG) SIZE_BYTES,
    (WORD) COLOR8,
    (WORD) PALETTE_SIZE,
    (WORD) WIDTH,
    (WORD) HEIGHT,
    palette,
    data
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Image Layer API Function

Advanced Video Driver

API Function

LONG CalypsoLoadImageLayer(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, const CALYPSOIMAGE *image);

Description

Load image from system to specified Display Layer in video memory.
When loading fullscreen background images the image width must equal the display layer width.
Works identically for 8 or 16 bit images.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Remarks

Note: This API function is provided for compatibility with Pluto 5/Calypso 16. This API function allows image loading from system memory. In general, Pluto 6/Calypso 32 will not use this function but will load images in .bmp bitmap format from a Compact Flash card.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame. DOUBLEBUFFER_FRAME1 - second double buffer frame.
image | Pointer to image structure.

Return Value

Next free address.

Code Example

/* demo.c */
extern const CALYPSOIMAGE bgnd;
LONG next;

/* load background image to Base Left Layer */
next  = CalypsoLoadImageLayer(&Calypso32PlusDevice, BL_LAYER,
                              DOUBLEBUFFER_FRAME0, &bgnd);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Image Convert 8 to 16 API Function

Advanced Video Driver

API Function

LONG CalypsoLoadImageConvert8to16(const DEVICE* dev, LONG video_addr, const CALYPSOIMAGE* image);

Description

Load image from system memory to video memory with 8-bit to 16-bit colour conversion.

Remarks

Special version of CalypsoLoadImage( )

Converts the image from 8-bit to 16-bit colour during the memory transfer process using the palette in the image structure. Image loading is slow (due to conversion), but gives 50 per cent saving in system memory space used to store the original image.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Note: This API function is provided for compatibility with Pluto 5/Calypso 16. This API function allows image loading from system memory. In general, Pluto 6/Calypso 32 will not use this function but will load images in .bmp bitmap format from a Compact Flash card.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
video_addr | Display Layer start address (offset from start of video memory).
image | Pointer to image structure.

Return Value

Next free address.

Code Example

/* demo.c */
extern const CALYPSOIMAGE bgnd;	/* 8-bit image */
LONG next_video_memory address;

/* load background image to start of video memory */
next_video_memory address  = CalypsoLoadImage (&Calypso32PlusDevice, 0, &bgnd);
/* mapped to 16-bit Base Left Layer*/
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Image Layer Convert 8 to 16 API Function

Advanced Video Driver

API Function

LONG CalypsoLoadImageLayerConvert8to16 (const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, const CALYPSOIMAGE *image);

Description

Load image from system memory to Display Layer with 8-bit to 16-bit colour conversion.

Remarks

Special version of CalypsoLoadImageLayer( )

Converts the image from 8-bit to 16-bit colour during the memory transfer process using the palette in the image structure.
Image loading is slow (due to conversion), but gives 50 per cent saving in EPROM space.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Note: This API function is provided for compatibility with Pluto 5/Calypso 16. This API function allows image loading from system memory. In general, Pluto 6/Calypso 32 will not use this function but will load images in .bmp bitmap format from a Compact Flash card.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame
image | Pointer to image structure.

Return Value

Next free address.

Code Example

/* demo.c */
extern const CALYPSOIMAGE bgnd;	/* 8-bit image */
LONG next;

/* load background image to Base Layer */
next = CalypsoLoadImageLayer (&Calypso32PlusDevice, BL_LAYER,
                              DOUBLEBUFFER_FRAME0, &bgnd);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Create Mask API Function

Advanced Video Driver

API Function

LONG CalypsoCreateMask(const DEVICE* dev,const UWORD* startaddr, LONG offset, LONG size);

Description

Create a transparency mask for a loaded .bmp bitmap image.

Remarks

This function works for .bmp bitmap images that have been loaded into video memory and converted from 24 to 16 bit colour.

The transparency colour of the image background must be black.

When using transparency masks it is advisable to create the mask after loading the associated image file. The mask is then placed immediately after the image data in video memory.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice.
startaddr | Address of sprite image in video memory.
offset | Memory offset from the start of video memory to beginning of mask.
size | Size of sprite image to mask in bytes.

Return Value

Offset from start of video memory to end of mask.

Code Example

/*definition of type */

typedef struct bmpspriteinfo
{
    BMPFILEINFO bmpinfo;
    ULONG start_address;
}BMPSPRITEINFO;

/* list of file names in Compact Flash */
static const BYTE*const animimages[]=
{
    "ball.bmp",
     ...
     0
};

/* local variables of a function*/
BMPSPRITEINFO ballbmp;
ULONG result;
ULONG offscreen;
BYTE** ptrpath;

/* Change to working directory */
ChangeDir(&ATADevice, "\\");
ChangeDir(&ATADevice, "images");

/* force variable to be offset of empty video memory*/
offscreen = offscreen_start;

ptrpath = animimages;

ballbmp.start_address = offscreen;

/* load bitmap into memory and return number of bytes loaded in video memory */
result = loadwindowsbmp(serialdevice,serialchannel,*ptrpath,
                        &ballbmp.bmpinfo, offscreen);

offscreen+= result;

/* create a mask for the image in the next avaiable memory location */
offscreen =
    CalypsoCreateMask(&Calypso32PlusDevice,
             ((const UWORD*)(ballbmp.start_address + 0x30000000),   /*start address of the image to mask*/
                       offscreen,  /*offset where to store the mask from start of video memory */
                       ballbmp.bmpinfo.imagewidth*ballbmp.bmpinfo.imageheight* BYTES_PER_PIXEL); /*nb of bytes to mask*/

/*-------------------------------------------------------------------

Name......... loadwindowsbmp()
Author....... Aymeric Dupont
Date......... 13/01/04
Description.. Load windows BMP Image and calculate next free memory address.
Parameters... 1) Serial device where to print debugging information.
............. 2) Channel for serial.
............. 3) string relating file to load.
............. 4) Pointer on a BMP strucutre.
............. 5) Offset in video memory where to load the bitmap.
Return....... Returns 0 when crashes.
............. Returns number of bytes loaded into memory if successful.
History...... 13/01/04 - First Pass - MP
-------------------------------------------------------------------*/
static ULONG loadwindowsbmp(const DEVICE* serialdevice, BYTE serialchannel,
                            const BYTE *filename, BMPFILEINFO *bmpinfo,
                            ULONG start_offset )
{
      BMPFILEINFO *bmpfileinfo;
      ULONG freememory,meminptr;
      UBYTE       result;
      ULONG nbbytes;
      BYTE str[50];

      /* Get free memory address at the end of the video memory to load temporarly image*/
      (ULONG)meminptr = (ULONG)0x31c00000;

      /* Create a pointer where to store the final image */
      (ULONG)freememory = (ULONG) (0x30000000 + start_offset);

      if (!(result = LoadMsWinBmp24(&ATADevice, filename, bmpinfo, (UWORD*)meminptr, freememory)))
      {
            /* File found and loaded */
            /* Get Pointer To BMP file information structure and populate */
            bmpfileinfo = bmpinfo;

            /* Calculate new start of free memory address */
            nbbytes=(bmpfileinfo->imagewidth*bmpfileinfo->imageheight) * BYTES_PER_PIXEL;
            return(nbbytes);
      }
      else
      {
            TxString(serialdevice,serialchannel,"FAIL LOADING\r");
            /* File not found of contained error so return error code */
            return(0);
      }
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


LoadAPI Function

Advanced Video Driver

API Function

LONG CalypsoLoadSprite(const DEVICE* dev, LONG video_addr, const CALYPSOIMAGE *image);

Description

Load image from system to video memory, then:
Create and load image mask to next video memory address.

Remarks

The image mask is required by function CremsonPutSprite() for transparent blitting.

The image width MUST be an even number.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Note: This API function is provided for compatibility with Pluto 5/Calypso 16. This API function allows image loading from system memory. In general, Pluto 6/Calypso 32 will not use this function but will load images in .bmp bitmap format from a Compact Flash card.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
video_addr | Display Layer start address (offset from start of video memory).
image | Pointer to image structure.

Return Value

Next free memory address.

Code Example

LONG sprite_addr1;
LONG sprite_addr2;
sprite_addr2 = CalypsoLoadSprite(&Calypso32PlusDevice, sprite_addr1, &sprite_image);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Put Sprite API Function

Advanced Video Driver

API Function

WORD CalypsoPutSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG image_start, LONG xsize, LONG ysize, LONG mode);

Description

Blit sprite from undisplayed video memory to Display Layer.

Remarks

Note: There is a hardware limitation with the Cremson Video Controller. The chip can only blit correctly sprites with widths that are a multiple of 8 bytes.

The advanced video driver contains a workaround that allows use of sprites widths that are not multiples of 8 pixels. The width may be any even number of pixels.

This workaround is only implemented when the sprites are loaded from System Memory using function CalypsoLoadSprite().

The workaround has NOT been implemented for sprites loaded from Compact Flash using LoadMsWinBmp24(), due to performance limitations. Sprites loaded from Compact Flash must have a width that is a multiple of 8 pixels.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame This parameter is ignored for console and window layers, which are not double buffered.
x | Layer x position.
y | Layer y position.
image_start | Start address of sprite image data in video memory.
xsize | Sprite width in pixels.
ysize | Sprite height in lines.
mode | NORMAL_MODE TRANSPARENT_MODE

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

CalypsoPutSprite(        &Calypso32PlusDevice,C_LAYER,
                                            DOUBLEBUFFER_FRAME0,
                                            200, 200,
                                            image.startadress,
                                            image.imagewidth , image.imageheight,
                                            NORMAL_MODE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Save Sprite API Function

Advanced Video Driver

API Function

WORD CalypsoSaveSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG save_address, LONG xsize, LONG ysize);

Description

Save Block (sprite) from Display Layer to undisplayed video memory.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame This parameter is ignored for console and window layers, which are not double buffered.
x | Layer x position.
y | Layer y position.
save_address | Destination address in video memory.
xsize | Sprite width in pixels.
ysize | Sprite height in lines.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

CalypsoPutSprite(    &Calypso32PlusDevice,C_LAYER,
                     DOUBLEBUFFER_FRAME0,
                     200, 200,
                     offscreen_start,
                     image.imagewidth , image.imageheight);

image2.startaddress = offscreen_start;
offscreen_start += image.imagewidth , image.imageheight * BYTE_PER_PIXEL;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Sprite API Function

Advanced Video Driver

API Function

WORD CalypsoClearSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG xsize, LONG ysize);

Description

Clear Block (sprite) in Display Layer. The sprite area is then filled with black.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame This parameter is ignored for console and window layers, which are not double buffered.
x | Layer x position.
y | Layer y position.
xsize | Sprite width in pixels.
ysize | Sprite height in lines.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

/*old sprite is cleared*/
CalypsoClearSprite(&Calypso32PlusDevice,
                    ML_LAYER, DOUBLEBUFFER_FRAME0,
                    old_x,old_y,
                    kingadv.width,kingadv.height);

/* new sprite is displayed */
CalypsoPutSprite(&Calypso32PlusDevice,
                    ML_LAYER, DOUBLEBUFFER_FRAME0,
                    king_x,
                    king_y,
                    king_sprite,
                    kingadv.width,
                    kingadv.height,
                    NORMAL_MODE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Fill Sprite API Function

Advanced Video Driver

API Function

WORD CalypsoFillSprite(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG x, LONG y, LONG xsize, LONG ysize, UWORD color, UBYTE mode);

Description

Fill Block (sprite) in Display Layer with colour value.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame This parameter is ignored for console and window layers, which are not double buffered.
x | Layer x position.
y | Layer y position.
xsize | Sprite width in pixels.
ysize | Sprite height in lines.
color | Fill colour. The colour depth (8-bit or 16-bit) should match the Display Layer colour depth.
mode | Fill mode: BLT_COPY - overwrite current pixels. BLT_AND - logical AND with current pixels. BLT_OR - logical OR with current pixels.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

CalypsoFillSprite( &Calypso32PlusDevice, ML_LAYER,
                   DOUBLEBUFFER_FRAME0,
                   100, 100,
                   16, 16,
                   0x7C00,
                   BLT_COPY);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set ASCII Font API Function

Advanced Video Driver

API Function

void CalypsoSetAsciiFont(const DEVICE* dev, const CALYPSOFONT *font);

Description

Set the current ASCII text font.

Remarks

Font source files can be generated from TrueType font files using Heber utility: fontconv.bat.

The utility will produce a source file font_name.c containing font data in the following structure:

const CALYPSOFONT image_name =
{
    font parameters …
    bit-map data…
};

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
font | Pointer to font structure.

Return Value

None.

Code Example

CalypsoSetAsciiFont(&Calypso32PlusDevice, &tempo16_0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Text Colour API Function

Advanced Video Driver

API Function

WORD CalypsoSetTextColor(const DEVICE* dev, UWORD foreground_color, UWORD background_color);

Description

Set current text colour.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
foreground_color | Foreground colour (8 or 16 bit colour).
background_color | Background colour (8 or 16 bit colour).

Return Value

None.

Code Example

CalypsoSetTextColor(&Calypso32PlusDevice, RED, WHITE); /* 8-bit */
CalypsoSetTextColor(&Calypso32PlusDevice, 0x1234, 0x0000); /* 16-bit */
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Text Position API Function

Advanced Video Driver

API Function

void CalypsoSetTextPosition(const DEVICE* dev, LONG layer_select, WORD x, WORD y);

Description

Set Display Layer current text writing position.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
x | Screen x co-ordinate in pixels. x=0 - screen left.
y | Screen y co-ordinate in display lines. y=0 - screen top.

Return Value

None.

Code Example

CalypsoSetTextPosition(&Calypso32PlusDevice, ML_LAYER, SCREEN1_WIDTH / 2, SCREEN1_HEIGHT / 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Text Position X API Function

Advanced Video Driver

API Function

WORD CalypsoGetTextPositionX(const DEVICE* dev, LONG layer_select)

Description

Get current text writing position x coordinate for layer.

Parameters

Parameter | Description
dev | Pointer to device.
layer_select | Display layer.

Return Value

x position in pixels from left of screen.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Put Char API Function

Advanced Video Driver

API Function

WORD CalypsoPutChar(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, UBYTE ch);

Description

Write text character to Display Layer at current layer writing position.
Current writing position advances after character is written.

Note: writing position is BOTTOM LEFT of character.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer Note: It is recommended that text be written to a non double-buffered display layer: console (C_LAYER) or window layer (W_LAYER). If the base or middle layer are used, they should be in single-buffered mode. This will avoid the complication of writing the same text twice (once to each double buffer frame).
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame
ch | ASCII Character code 0x00-0x7F.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

WORD x;
WORD y;

x=0;
y=32;	/* NOTE: writing position is BOTTOM LEFT of character */

/* start writing at top left of screen*/
CalypsoSetTextPosition(&Calypso32PlusDevice, C_LAYER, x, y);
CalypsoPutChar(&Calypso32PlusDevice, C_LAYER,  0, ’A’);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Put Str API Function

Advanced Video Driver

API Function

WORD CalypsoPutStr(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, BYTE *str);

Description

Write text string string to Display Layer at current layer writing position.
Current writing position advances after string is written.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame DOUBLEBUFFER_AUTO - currently non-displayed double buffer frame. This parameter is ignored for console and window layers, which are not double buffered.
str | Null terminated text string.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

WORD x;
WORD y;

x=0;
y=32;	/* NOTE: writing position is BOTTOM LEFT of character */

/* start writing at top left of screen*/
CalypsoSetTextPosition(&Calypso32PlusDevice, C_LAYER, x, y);
CalypsoPutStr(&Calypso32PlusDevice, C_LAYER, 0, "--Calypso 32--");
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Unicode API Function

Advanced Video Driver

API Function

void CalypsoSetUnicodeFont(const DEVICE* dev, const CALYPSOFONT *font, UWORD unicode_page)

Description

Assign Unicode font to code page.

Remarks

Font source files can be generated from TrueType font files using Heber utility: fontconv.bat.

The utility will produce a source file font_name.c containing font data in the following structure:

const CALYPSOFONT image_name =
{
    font parameters …
    bit-map data…
};

See also further information on Unicode characters.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
font | Pointer to Calypso Unicode font.
unicode_page | Start of corresponding Unicode code page.

Return Value

None.

Code Example

See example in CalypsoPutUnicodeChar.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Unicode Font API Function

Advanced Video Driver

API Function

CALYPSOFONT *CalypsoGetUnicodeFont(const DEVICE* dev, UWORD unicode_page)

Description

Returns the Unicode Font assigned to Unicode code page.

Remarks

Font source files can be generated from TrueType font files using Heber utility: fontconv.bat.

The utility will produce a source file font_name.c containing font data in the following structure:

const CALYPSOFONT image_name =
{
    font parameters …
    bit-map data…
};

See also further information on Unicode characters.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
unicode_page | Start of corresponding Unicode code page.

Return Value

Pointer to font assigned to page.
Returns NULL if no font assigned.

Example

See example in CalypsoPutUnicodeChar().

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Put Unicode Char API Function

Advanced Video Driver

API Function

WORD CalypsoPutUnicodeChar(const DEVICE* dev, CALYPSOLAYER* layer, BYTE doublebuffer_frame, UWORD ch)

Description

Write Unicode character to display layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame
ch | Unicode character 0x0000 - 0x7FFF. Encoding: UTF16 big endian.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

Code Example

/* Assign and Display Unicode Fonts */
#define N_UNICODE_PAGES	512

extern const CALYPSOFONT example16_0;
extern const CALYPSOFONT example16_80;
extern const CALYPSOFONT example16_100;
extern const CALYPSOFONT example16_180;
extern const CALYPSOFONT example16_200;
extern const CALYPSOFONT example16_380;
extern const CALYPSOFONT example16_400;

UWORD ch;	/* Unicode character UTF16 */
UWORD codepage;

CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_0, 0x0);
CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_80, 0x80);
CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_100, 0x100);
CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_180, 0x180);
CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_200, 0x200);
CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_380, 0x380);
CalypsoSetUnicodeFont(&Calypso32PlusDevice, &example16_400, 0x400);

for(n=0, codepage=0; n < N_UNICODE_PAGES;  n++)
{
     /* check if font has been assigned to this unicode page */
    if(CalypsoGetUnicodeFont(&Calypso32PlusDevice, codepage) != NULL)
    {
        for(ch=0; ch<128; ch++)
        {
            CalypsoPutUnicodeChar(&Calypso32PlusDevice, C_LAYER,
                                  0, codepage + ch);
        }
    }
    codepage += 0x80;
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Put Unicode Str API Function

Advanced Video Driver

API Function

WORD CalypsoPutUnicodeStr(const DEVICE* dev, CALYPSOLAYER* layer, BYTE doublebuffer_frame, UWORD *str)

Description

Write Unicode string to display layer. Each character in string (array of 16-bit unsigned WORDS) is in UTF-16 big-endian format. Characters must be in Unicode range 0000 - 0xFFFF (64K characters).

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
doublebuffer_frame | Display Layer double buffer frame: DOUBLEBUFFER_FRAME0 - first double buffer frame DOUBLEBUFFER_FRAME1 - second double buffer frame
str | Pointer to null-terminated array of 16 bit Unicode characters.

Return Value

Return 0 if successful.
Return 1 if the display list is full.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Define Animation API Function

Advanced Video Driver

API Function

void CalypsoDefineAnimation(const DEVICE* dev, ANIMATION* anim,
CALYPSOLAYER* layer, UWORD n_frames, WORD x, WORD y, WORD dx, WORD dy,
LONG image_start, LONG image_offset, WORD n_images, WORD image_index,
LONG width, LONG height, BYTE type, LONG mode,
LONG buffer1, LONG buffer2, void (*update)(ANIMATION* anim))

Description

Define in full an animation sequence.

Remarks

An animation sequence is any defined succession of graphics images. Examples are moving sprites, and video clips.

The standard video driver requires the developer to explicitly write code to handle timing, double buffering and synchronisation with vertical interrupt.

The enhanced driver allows all parameters of an animation sequence to be specified in advance. The animation can then be started with a single command: all screen updates will be taken care of automatically by the driver.

Each animation defined relates to a single screen object, and has an associated ANIMATION structure. A maximum of 8 animations can be active at any one time.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation structure associated with the animation.
layer | The display layer in which the animation will run.
n_frames | total number of display frames in the animation. (0 < n_frames < 32768) - run forever if n_frames= ANIMATION_RUN_FOREVER
x | Start position – x coordinate in pixels.
y | Start position – y coordinate in display.
dx | Initial x speed – pixels per animation frame.
dy | Initial y speed – lines per animation frame.
image_start | Start address in video memory of first image in sequence.
image_offset | Multiple image sequence: video memory offset between images for consecutive frames.
n_images | Multiple image sequence: number of separate images.
image_index | Multiple image sequence: current image index.
width | Image width in pixels. All images in an animation must be the same size.
height | Image height in lines. All images in an animation must be the same size.
type | Set the type of animation to be performed. ANIMATION_TYPE1 - update position, put next image. ANIMATION_TYPE2 - clear previous image, update position, put next image. ANIMATION_TYPE3 - restore image background, update position,save image background, put next image.
mode | Blit mode: NORMAL_MODE TRANSPARENT_MODE
buffer1 | If type =ANIMATION_TYPE3 - address of buffer in video memory for storing image background. (Double buffer frame 0) Otherwise set to zero.
buffer2 | If type =ANIMATION_TYPE3 - address of buffer in video memory for storing image background. (Double buffer frame 1) Otherwise set to zero.
update | Pointer to user supplied update function - calculates next x,y position.

Return Value

None.

Code Example

ANIMATION example_anim;

/* Load fifteen images of spinning dice to video memory */

dice_start[0]	= sprite_start;
dice_start[1]	= CalypsoLoadSprite(&Calypso32PlusDevice, dice_start[0], &dice1);
dice_start[2]	= CalypsoLoadSprite(&Calypso32PlusDevice, dice_start[1], &dice2);
/* etc */
/* etc */
dice_start[13]	= CalypsoLoadSprite(&Calypso32PlusDevice, dice_start[12],&dice13);
dice_start[14]	= CalypsoLoadSprite(&Calypso32PlusDevice, dice_start[13],&dice14);

save_buffer[0]	= CalypsoLoadSprite(&Calypso32PlusDevice, dice_start[14],&dice15);
dice_size_bytes = dice_start[1] - dice_start[0];
save_buffer[1]	= save_buffer[0] + dice_size_bytes;

/* define animation */

CalypsoDefineAnimation( &Calypso32PlusDevice,    /* Advanced Video Device */
                        &example_anim,
                        BL_LAYER,		      /* Base Left Layer */
                        ANIMATION_RUN_FOREVER,   /* run forever */
                        0,0,                     /* startx=0, starty=0 */
                        2,4,                     /* x_speed=2, y_speed=4 */
                        dice_start[0],           /* address of first image */
                        dice_size_bytes,         /* frame offset */
                        15,                      /* images in sequence */
                        0,                       /* current image index */
                        dice1.width,             /* image width */
                        dice1.height,            /* image height */
                        ANIMATION_TYPE3,         /* restore/update/save/put */
                        TRANSPARENT_MODE,        /* transparent blit */
                        save_buffer[0],          /* background save buffer 1 */
                        save_buffer[1],          /* background save buffer 2 */
                        edgebounce );            /* update function */

/* add animation to list */
CalypsoAddToAnimationList(&Calypso32PlusDevice, &example_anim);

/* start animation */
CalypsoSetFrameRate(&Calypso32PlusDevice, FRAME_30HZ);
CalypsoStartAnimation(&Calypso32PlusDevice, &example_anim);

/* After the animation has started, any of the following commands can be used
subsequently…*/

/* pause animation */
CalypsoPauseAnimation(&Calypso32PlusDevice, &example_anim);

/* single step animation */
CalypsoStepAnimation(&Calypso32PlusDevice, &example_anim);

/* stop animation */
CalypsoStopAnimation(&Calypso32PlusDevice, &example_anim);

/* clear list */
CalypsoClearAnimationList(&Calypso32PlusDevice);

/* EXAMPLE: update function */
static void edgebounce(ANIMATION *anim)
{
    /* screen limits */
    WORD xlo;
    WORD ylo;
    WORD xhi;
    WORD yhi;

    /* define screen limits */
    xlo = 0;
    ylo = 0;
    xhi = H_SIZE - anim->width;
    yhi = V_SIZE - anim->height;

    /* new position = old position + speed */
    anim->x += anim->dx;
    anim->y += anim->dy;

    /* reverse direction at screen limits */
    if(anim->x < xlo)
    {
        anim->x = xlo; anim->dx = -anim->dx;
    }
    if(anim->y < ylo)
    {
        anim->y = ylo; anim->dy = -anim->dy;
    }
    if(anim->x > xhi)
    {
        anim->x = xhi; anim->dx = -anim->dx;
    }
    if(anim->y > yhi)
    {
        anim->y = yhi; anim->dy = -anim->dy;
    }
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Add to Anim List API Function

Advanced Video Driver

API Function

WORD CalypsoAddToAnimationList(const DEVICE* dev, ANIMATION* anim)

Description

Add an animation to the list of currently active animations.

Further Information

After an animation has been defined with function CalypsoDefineAnimation( ), it must be added to the Animation List. This is a list of currently active animations.

The animation can then be run, paused single-stepped or stopped using functions: CalypsoStartAnimation( ), CalypsoStopAnimation( ), CalypsoPauseAnimation( ), CalypsoStepAnimation( ).

A maximum of eight animations can be active at any time.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation.

Return Value

Returns 0 if successful.
Returns 1 if Animation List full.

Code Example

See example in CalypsoDefineAnimation( ).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Remove from Animation API Function

Advanced Video Driver

API Function

WORD CalypsoRemoveFromAnimationList(const DEVICE* dev, ANIMATION* anim)

Description

Remove an animation from the list of currently active animations.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation.

Return Value

Returns 0 if successful.
Returns 1 if animation not found.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Animation List API Function

Advanced Video Driver

API Function

void CalypsoClearAnimationList(const DEVICE* dev)

Description

Remove all animations from the Animation List.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice

Return Value

None.

Code Example

See example for CalypsoDefineAnimation( ).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Start Animation API Function

Advanced Video Driver

API Function

void CalypsoStartAnimation(const DEVICE* dev, ANIMATION* anim)

Description

Start an animation.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation.

Return Value

None.

Code Example

See example for CalypsoDefineAnimation( ).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stop Anim API Function

Advanced Video Driver

API Function

void CalypsoStopAnimation(const DEVICE* dev, ANIMATION* anim)

Description

Stop (finish) an animation.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation.

Return Value

None.

Code Example

See example for CalypsoDefineAnimation( ).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Pause Animation API Function

Advanced Video Driver

API Function

void CalypsoPauseAnimation(const DEVICE* dev, ANIMATION* anim)

Description

Pause an animation.
The animation can be resumed with CalypsoStartAnimation( )

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation.

Return Value

None.

Code Example

See example in CalypsoDefineAnimation( ).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Step Animation API Function

Advanced Video Driver

API Function

void CalypsoStepAnimation(const DEVICE* dev, ANIMATION* anim)

Description

Single step an animation.
Each call to CalypsoStepAnimation( ) will advance the animation by one frame.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
anim | Pointer to animation.

Return Value

None.

Code Example

See example for CalypsoDefineAnimation( ).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Point API Function

Advanced Video Driver

API Function

void CalypsoPoint(const DEVICE* dev, LONG layer_select, LONG x, LONG y, UWORD color);

Description

Draw pixel to Display Layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
x | X position in Display Layer.
y | Y position in Display Layer.
color | Pixel Colour 8 or 16 bit.

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Line API Function

Advanced Video Driver

API Function

void CalypsoLine(const DEVICE* dev, LONG layer_select, LONG Ax, LONG Ay, LONG Bx, LONG By, UWORD color);

Description

Draw line to Display Layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
Ax | Line start x co-ordinate.
Ay | Line start y co-ordinate.
Bx | Line end x co-ordinate.
By | Line end y co-ordinate.
Color | Line colour.

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Circle API Function

Advanced Video Driver

API Function

void CalypsoCircle(const DEVICE* dev, LONG layer_select, LONG xcentre, LONG ycentre, LONG radius, UBYTE color);

Description

Draw circle to Display Layer.

Parameters

Parameter | Description
dev | Advanced Video Device address - &Calypso32PlusDevice
layer_select | Display Layer: BL_LAYER - base left layer BR_LAYER - base right layer ML_LAYER - middle left layer MR_LAYER - middle right layer W_LAYER - window layer C_LAYER - console layer
xcentre | X co-ordinate of centre of circle.
ycentre | Y co-ordinate of centre of circle.
radius | Radius of circle.
color | Colour of circle.

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso x API Function

Advanced Video Driver

API Function

WORD CalypsoGetDisplayHsize(const DEVICE* dev)

Description

Displays the horizontal screen size in pixels.

Parameters

Parameter | Description
device | Advanced Video Device address - &Calypso32PlusDevice.

Return Value

Value of the horizontal screen size.

Code Example

Xsize = CalypsoGetDisplayHsize((&Calypso32PlusDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso x API Function

Advanced Video Driver

API Function

WORD CalypsoGetDisplayVsize(const DEVICE* dev)

Description

Displays the vertical screen size in lines.

Parameters

Parameter | Description
device | Advanced Video Device address - &Calypso32PlusDevice.

Return Value

Value of the vertical screen size.

Code Example

Ysize = CalypsoGetDisplayVsize (&Calypso32PlusDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Sync Lock Enable API Function

Advanced Video Driver

API Function

void CalypsoSyncLockEnable(const DEVICE* dev, BYTE enable);

Description

Synchronise the Display Scan of the second video board to the first video board.

Remarks

In some circumstances it may prove necessary or desirable to virtically synchronise the two Calypso 32 boards if the following problems arise:

  • On-screen interference between adjacent monitors, if inadequately shielded. This is usually seen as slow moving horizontal bars.
  • Subtle software timing problems may occur as the two vertical interrupts drift in and out of phase. The interrupt routines are long (several ms) and of equal priority. This will result in periodic long delays before execution for each interrupt.

The current modifications to the Pluto 6 board will allow one Calypso 32 board to be vertically synchronised with the second board.

Parameters

Parameter | Description
dev | Advanced Video Device address - IGNORED
enable | Enable synchronisation: 1 - Enable 0 - Disable

Return Value

None.

Code Example

/* Synchronise the display signals of the two video boards */

#define SYNC_DISABLE   0
#define SYNC_ENABLE    1

CalypsoSyncLockEnable(&Calypso32Dual0Device, SYNC_ENABLE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Set Line API Function

Advanced Video Driver

API Function

WORD CalypsoSetLineProperties (const DEVICE* dev, UBYTE width)

Description

Set line width (use in AdvanceLine and AdvanceRectangle API functions).

Parameters

Parameter | Description
dev | Pointer to device.
width | Width of the line (from 1 pixel to 32 pixels).

Return Value

Normally 0.
Returns 1 if display list full.

Code Example

CalypsoSetLineProperties(&Calypso32Dual0Device, 7); /* set width to 7 pixels*/
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Advance Line API Function

Advanced Video Driver

API Function

WORD CalypsoAdvanceLine(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG Ax, LONG Ay, LONG Bx, LONG By,UWORD color)

Description

Draws line to display layer between points A and B. The line will have the width define using CalypsoSetLineProperties.

Parameters

Parameter | Description
dev | Pointer to device.
layer_select | Display layer.
doublebuffer_frame | Double buffer frame.
Ax | Start x coordinate.
Ay | Start y coordinate.
Bx | End x coordinate.
By | End y coordinate.
color | Colour value (8/16 bit).

Return Value

Normally 0.
Returns 1 if display list full.

Code Example

/* display horizontal line of 800 pixels*/
    CalypsoAdvanceLine(&Calypso32Dual0Device, C_LAYER,
                DOUBLEBUFFER_FRAME0,
                0, 150, 800, 150,
                COLOR_PURE_RED);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Alpha Blend API Function

Advanced Video Driver

API Function

WORD CalypsoAdvanceRectangle(const DEVICE* dev, LONG layer_select, BYTE doublebuffer_frame, LONG left, LONG top, LONG right, LONG bottom, UWORD color)

Description

Draw an empty rectangle on the screen. The surrounding will have the width define using CalypsoSetLineProperties.

Parameters

Parameter | Description
dev | Pointer to device.
layer_select | Display layer.
doublebuffer_frame | Double buffer frame.
left | Rectangle top X co-ordinate relative to Top Left of screen.
top | Rectangle top Y co-ordinate relative to Top Left of screen.
right | Rectangle bottom X co-ordinate relative to Top Left of screen.
bottom | Rectangle bottom Y co-ordinate relative to Top Left of screen.
color | Colour value (8/16 bit).

Return Value

Normally 0.
Returns 1 if display list full.

Notes

  1. Better results are achieved if the line width is an odd number.
  2. Be careful with coordinate provided to this function (ex: if trying to draw a rectangle at edge of the of maximum resolution ex: 800*600. If the width of the line is 30 pixel, it will draw on another layer).

Code Example

CalypsoAdvanceRectangle(&Calypso32Dual0Device, C_LAYER,
                    DOUBLEBUFFER_FRAME0,
                    50, 50, 350, 550,COLOR_RED);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Advance Clear Line API Function

Advanced Video Driver

API Function

void CalypsoAdvanceClearLineAntiAlias(void);

Description

Turns off anti-aliasing when using the advance line drawing functions.

Parameters

None.

Return Value

None.

Code Example

                              /* set the line width to 4 pixels */
CalypsoSetLineProperties(&Calypso32Dual0Device, 4);
                              /* clear the anti aliasing */
CalypsoAdvanceClearLineAntiAlias();
                              /* draw line */
CalypsoAdvanceLine(&Calypso32Dual0Device, C_LAYER,
                     DOUBLEBUFFER_FRAME0,
                     200, 200, 400, 400,
                     0x4000);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso Advance Set Line API Function

Advanced Video Driver

API Function

void CalypsoAdvanceSetLineAntiAlias(void);

Description

Turns on anti-aliasing when using the advance line drawing functions.

Parameters

None.

Return Value

None.

Code Example

                              /* set the line width to 4 pixels */
CalypsoSetLineProperties(&Calypso32Dual0Device, 4);
                              /* set the anti aliasing */
CalypsoAdvanceSetLineAntiAlias();
                              /* draw line */
CalypsoAdvanceLine(&Calypso32Dual0Device, C_LAYER,
                     DOUBLEBUFFER_FRAME0,
                     200, 200, 400, 400,
                     0x4000);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Performance Limitations

Calypso 32 supports 8 bit colour (256 colours) with up to 4 layers at all screen resolutions. Calypso 32 also supports 16 bit colour (32,768 colours). However, at certain screen resolutions and depending on the number of layers used, there is on-screen video disturbance. This is because the higher the resolution and the more layers that are used, the more data that is needed to be written to and read from memory. The performance limits are fixed by the memory bandwidth between the Cremson graphics display controller and the SDRAM video memory. On-screen disturbances occurs when the required memory bandwidth is greater than the maximum memory bandwidth.

The required memory bandwidth increases with:

  • screen resolution
  • colour depth
  • number of active display layers
  • CPU to video memory activity
  • Cremson drawing activity

When on-screen disturbances occur, possible solutions are:

  • reducing the number of layers
  • reducing the colour resolution of the layers
  • reducing the resolution of the layers

Heber recommends that only a certain number of layers are used at particular screen resolutions, as detailed in the table below.

Achievable Performance

Resolution (pixels) | 8 Bit Colour |  |  |  | 16 Bit Colour
 | 1 Layer | 2 Layers | 3 Layers | 4 Layers | 1 Layer | 2 Layers | 3 Layers | 4 Layers
640 x 480 |  |  |  |  |  |  |  |
800 x 600 |  |  |  |  |  |  |  |
1024 x 768 |  |  |  |  |  |  |  |

Key

: OK to use these number of layers at this particular resolution.
: Bandwidth limitation produces possible screen disturbances. Heber advises not to use.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Colour Modes

The Fujitsu Cremson video processor supports two colour modes:

  • 8 bit (INDIRECT)
  • 16 bit (DIRECT)

Colour modes supported on specific video layers are as follows:

Layer | Supported modes
Base | 8 and 16 bit
Middle | 8 and 16 bit
Window | 16 bit
Console | 8 and 16 bit

8 bit Indirect Colour

In this mode each pixel is represented by an 8 bit code. The code is used as a reference into a 256 value colour palette. The colours in the palette are selected from a possible 262,144 colours.

16 bit Direct Colour

In this mode each pixel is represented by a 16 bit code; five bits are used for Red, Green and Blue and one bit as a reserved intensity code (bit 15). This mode will allow up to 32,768 colours to be displayed.

The 16 bits of the colour value are as follows:

INT | RED |  |  |  |  | GREEN |  |  |  |  | BLUE
15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Transparency

Calypso 32 Transparency and Overlay Transparency

A transparency colour can be set for each of the video display layers when the layer is initialised. The following priority rules apply for transparency settings and image overlays:

  1. The Console layer has the highest priority. Any image displayed on this layer will overlay all other layers. If there is a transparent area on the Console layer the Window layer will be visible.
  2. The Window layer has the next highest priority. An image displayed on the Window layer will overlay images on the Middle and Base layers. If there is a transparent area on the Window layer the Middle layer will be visible.
  3. The Middle layer has the next highest priority. An image displayed on the Middle layer will overlay an image on the Base layer. If there is a transparent area on the Middle layer the Base layer will be visible.
  4. The Base layer has the lowest priority. Setting the transparency area on the Base layer has no effect.

For further information, see also Transparency Parameter.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Architecture

Calypso 32 Video Layer Architecture

The Fujitsu Cremson video processor supports six logical graphics fields arranged in four logical display layers.

Four Logical Display Layers

Base Layer | The Base layer is split vertically into left and right display fields. It is possible to set one of the display fields to represent the dimensions of the physical display. In this case the layer behaves as though it has a single display field.
Middle Layer | The Middle layer is split vertically into left and right display fields. It is possible to set one of the display fields to represent the dimensions of the physical display. In this case the layer behaves as though it has a single display field.
Window Layer | The Window layer contains a single display field.
Console Layer | The Console layer contains a single display field.

Logical Graphics Fields

Console Layer | The Console layer (C-Layer) display field has the highest display priority. It contains a single display field that can display 8 or 16 bits per pixel images.
Window Layer | The Window layer (W-Layer) display field has the second highest display priority. It contains a single display field that can display 16 bits per pixel images.
Middle Layer | The Middle left layer (ML-Layer) and Middle right layer (MR-Layer) display fields have the third highest display priority. The display fields can display 8 or 16 bits per pixel images.
Base Layer | The Base left layer (BL-Layer) and Base right layer (BR-Layer) display fields have the fourth highest display priority. The display fields can display 8 or 16 bits per pixel images.

Calypso 32 Layer Architecture

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Transparency

Transparency Parameter

Transparency within a screen layer is useful for blitting irregular shapes.
For example, the background colour is set to be blue and a user wants to load this sprite to the display screen.

The image represents a cherry on a black background.

If the image is loaded without transparency, the black background is loaded onto the screen, as follows:

If the image is loaded with transparency, the black background of the image is not modifying the blue background of the layer, as follows:

Note: The transparent colour within the sprite image is always colour=0.

Code Example

Loading a sprite without transparency at coordinate (0,0) (for example, the ball loaded in example sample from Createmask function):

PutSprite(HSIZE*VSIZE*BYTES_PER_PIXEL,
0, 0 HSIZE,
ball.start_address,
ball.bmpinfo.imagewidth,
ball.bmpinfo.imageheight, 0, BYTES_PER_PIXEL);

Loading the same sprite but with transparency at coordinate (0,0):

PutSprite(HSIZE*VSIZE*BYTES_PER_PIXEL,
0,0, HSIZE,
ball.start_address,
ball.bmpinfo.imagewidth,
ball.bmpinfo.imageheight, 1, BYTES_PER_PIXEL);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Advanced Video Driver Configuration Data

The following structure in the config.c file in the project directory allows configuration of the video processor using the Advanced Video Driver for specific display dimensions.

/**** Calypso 32 Advanced Video */

const    CALYPSO32PLUSCFG         Calypso32PlusCfg[]=
            {
            {Calypso800x600, palette, CALYPSO32PLUS_BASE, CalypsoPlusISR, IntVideoLst, CalypsoPlusISR1ms},
            {0}
            };

const    CALYPSO32PLUSCFG         Calypso32Dual0Cfg[]=
            {
            {Calypso800x600, palette, CALYPSO32DUAL0_BASE, Calypso0ISR, IntVideo0Lst, Calypso0ISR1ms},
            {0}
            };

const    CALYPSO32PLUSCFG         Calypso32Dual1Cfg[]=
            {
            {Calypso800x600, palette, CALYPSO32DUAL1_BASE, Calypso1ISR, IntVideo1Lst, Calypso1ISR1ms},
            {0}
            };

Supported Display Resolutions

The following display resolutions are supported by the video processor and can be used for the Advanced Video Driver configuration:

Resolution | Configuration Value
640x480 | Calypso640x480
768x576 | Calypso768x576
800x600 | Calypso800x600
1024x768 | Calypso1024x768
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Display List Handling

The Cremson display controller uses display lists. A display list is a sequential list of graphics commands and parameters. It is placed in video memory by the CPU and accessed and executed independently by the Cremson video processor.

Performance and structure have been improved by separating display list creation from execution.
A major benefit of this structure is that all API function calls are non-blocking:

Video Driver

GraphicsFunction(..)
  {
  ...
  createdisplaylist(..)
  rundisplaylist(..) /* BLOCKING - returns on completion*/
  }

Advanced Video Driver

GraphicsFunction(..)
  {
  ...
  addtodisplaylist(..) /* NON-BLOCKING */
  }
  VerticalInterrupt()
  {
  ...
  rundisplaylist(..)
  }

Multiple display lists are used. The driver cycles through the display lists, executing one display list every video frame. The display list currently being written to lags two frames behind the display list currently being executed.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Layer-centric Commands

The standard Pluto 6 Video driver API requires the game coder to explicitly keep track of memory addresses. The Advanced Pluto 6 Video driver API eliminates this by making all graphics functions layer-centric. All blitting/drawing functions have a parameter defining which display layer is being written to.

A simple example is blitting a sprite image to a display layer:

Video Driver

Initialise MIDDLE LEFT layer to memory address A
...
Put sprite to address A

Advanced Video Driver

Initialise MIDDLE LEFT layer to memory address A
...
Put sprite to MIDDLE LEFT layer
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Colour Depth Issues

A major benefit of layer-centric commands is that they remove the need to specify colour depths within user code (other than at configuration/initialisation).

Colour depth is a defined property of the display layers. If the blitting and drawing commands specify which display layer is being written to, the correct version of the function can be run depending on the known colour depth of that layer.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Alpha Blending

Alpha Blending can be used to create the effect of transparency and fading in video graphics. API functions have been added to support Alpha Blending between the console layer and other layers.

See the following Alpha Blending API functions for further information:

  • CalypsoAlphaBlend
  • CalypsoSetBlendRatio
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Unicode Character Support

Unicode Character Support allows text display of character sets such as Cyrillic and Greek.

Supported features include:

  • creation of and loading of fonts covering specified Unicode character ranges.
  • displaying of UTF-16 encoded Unicode characters.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Animation Sequence

An animation sequence is any defined succession of graphics images. Examples are moving sprites, and video clips.

The standard Video driver requires the developer to explicitly write code to handle timing, double buffering and synchronisation with vertical interrupt.

The Advanced Video Driver allows all parameters of an animation sequence to be specified in advance. The animation can then be started with a single command. The Advanced Video Driver automatically handles all screen updates.

This will allow the game developer to simplify his animation code:

Example

DefineAnimation(EyeCandy, parameters...)
  ...
  RunAnimation(EyeCandy)
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Driver Address Map

The Calypso 32 boards are mapped into the system memory in 32 Mbyte segments at the following address ranges:

First Calypso 32 Board | 0x30000000 - 0x31FFFFFF | 32M
- Video Memory | 0x30000000 - 0x31FBFFFF | 32M - 256K
- Cremson Registers | 0x31FC0000 - 0x31FFFFFF | 256K
Second Calypso 32 Board | 0x34000000 - 0x35FFFFFF | 32M
- Video Memory | 0x34000000 - 0x35FBFFFF | 32M - 256K
- Cremson Registers | 0x35FC0000 - 0x35FFFFFF | 256K

NOTES:

  1. The video memory for each board is mapped into the system address space and can be directly accessed by the CPU.
  2. Each graphics controller can only directly access its own video memory.
  3. At the game/application programming level, it is not necessary to specify absolute addresses when using the API functions. The driver uses the device parameter in each function to select the memory or register address for the selected video board. In addition, the API functions specify video memory addresses as offsets from a base address.
  4. Some image loading functions in other driver modules require the destination video memory address to be specified as an absolute address. An example is the bit map image loading function LoadMsWinBmp24() in the Standard Interface Module. When using these functions it will be necessary to use the memory addresses specified in the above table.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Driver Configuration Data

General

The Calypso 32 driver uses the following configuration structure:

typedef struct calypso32pluscfg
{
    const WORD *screenmode; /* Initial display resolution. Valid options are: */
                            /*    Calypso1024x768                             */
                            /*    Calypso800x600                              */
                            /*    Calypso640x480                              */

    const PALETTE_RGB *palette; /* Default palette                                */

    LONG base_address;      /* System base address of video card. Valid       */
                            /* options are:                                   */
                            /*    CALYPSO32PLUS_BASE   (single video board)   */
                            /*    CALYPSO32DUAL0_BASE  (dual video 1st board) */
                            /*    CALYPSO32DUAL1_BASE  (dual video 2nd board) */

    void (*isr)();          /* Interrupt Service Routine (ISR). Valid options */
                            /* are:
                            /*    CalypsoPlusISR       (single video board)   */
                            /*    Calypso0ISR          (dual video 1st board) */
                            /*    Calypso1ISR          (dual video 2nd board) */

    void (**fnc_lst)();     /* Interrupt List. The above ISR is added to this */

    void (*isr1ms)();       /* 1ms Interrupt Service Routine. Valid options   */
                            /* are:
                            /*    CalypsoPlusISR1ms    (single video board)   */
                            /*    Calypso0ISR1ms       (dual video 1st board) */
                            /*    Calypso1ISR1ms       (dual video 2nd board) */
} CALYPSO32PLUSCFG;

Each instantiation of the driver requires an install line in the project file devices.c in addition to the following declarations in config.c:

  • Video interrupt list.
  • Configuration structure.

Single Video System

/* devices.c */
const INSTALLDEVICE DeviceList[] =
{
    ...
    {&Calypso32PlusDevice, 0, 0, 0},
    ...
};

/* config.c */

/* video interrupt list */
void (*IntVideoLst[])() = { 0, 0, 0, 0, 0, 0, 0, 0, 0, EOF_FUNCTIONS };

/* configuration structure */
const CALYPSO32PLUSCFG Calypso32PlusCfg[] =
{
    {
        Calypso800x600,
        std_palette,
        CALYPSO32PLUS_BASE,
        CalypsoPlusISR,
        IntVideoLst,
        CalypsoPlusISR1ms
    },
    0
};

Dual Video System

/* devices.c */
const INSTALLDEVICE DeviceList[] =
{
    ...
    {&Calypso32Dual0Device, 0, 0, 0},
    {&Calypso32Dual1Device, 0, 0, 0},
    ...
};

/* config.c */

/* video interrupt list */
void (*IntVideo0Lst[])() = { 0, 0, 0, 0, 0, 0, 0, 0, 0, EOF_FUNCTIONS };
void (*IntVideo1Lst[])() = { 0, 0, 0, 0, 0, 0, 0, 0, 0, EOF_FUNCTIONS };

/* configuration structure - first video board */
const CALYPSO32PLUSCFG Calypso32Dual0Cfg[] =
{
    {
        Calypso800x600,
        std_palette,
        CALYPSO32DUAL0_BASE,
        Calypso0ISR,
        IntVideo0Lst,
        Calypso0ISR1ms
    },
    0
};

/* configuration structure - second video board */
const CALYPSO32PLUSCFG Calypso32Dual1Cfg[] =
{
    {
        Calypso800x600,
        std_palette,
        CALYPSO32DUAL1_BASE,
        Calypso1ISR,
        IntVideo1Lst,
        Calypso1ISR1ms
    },
    0
};

Additional Configuration

The following declarations must be added to the project files:

/* fpga.h */

/*************************************************/
/* FPGA Register Bit Definitions                 */
/*************************************************/

/* XCRA Control Register A */
#define SYNC_ENABLE     0x10 /* dual video: synchronise second video board to
                                first video board */

/* fpga.c */

/* XCRA - control register A */
UBYTE Syncenable = SYNC_ENABLE;

/*************************************************/
/* Calypso 32 Base Address Definitions           */
/*************************************************/

#define CALYPSO32PLUS_BASE   (LONG)(0x30000000)                /* CS3 */
#define CALYPSO32DUAL0_BASE  (LONG)(0x30000000)                /* CS3 */
#define CALYPSO32DUAL1_BASE  (LONG)(0x30000000+0x4000000)      /* CS3 + 64M */

Supported Display Resolutions

The following display resolutions are supported by the video processor and can be used for the Dual Video Driver configuration:

Resolution | Configuration Value
640x480 | Calypso640x480
768x576 | Calypso768x576
800x600 | Calypso800x600
1024x768 | Calypso1024x768
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Driver Device Parameter

All the API functions in the Calypso 32 Advanced Driver include a device parameter. This identifies the video board to which the function refers:

Calypso32SomeFunction(const DEVICE *dev, parameter list...)

Where dev is one of the following:

dev | Description
&Calypso32Dual0Device | Dual video system: First board
&Calypso32Dual1Device | Dual video system: Second board

Code Example

/* first video board: load and display background */

CalypsoLoadImage(&Calypso32Dual0Device,bgnd0_start,&bgnd);
CalypsoPutSprite(&Calypso32Dual0Device,BL_LAYER,0,0,0,bgnd0_start,bgnd0.width,
        bgnd0.height,0);

/* second video board: load and display same background */

CalypsoLoadImage(&Calypso32Dual1Device,bgnd1_start,&bgnd);
CalypsoPutSprite(&Calypso32Dual1Device,BL_LAYER,0,0,0,bgnd1_start,bgnd1.width,
        bgnd1.height,0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Driver Interrupts

Each instantiation of the driver installs the following interrupt handlers:

  1. Vertical interrupt handler. This is installed in an interrupt list specific to that video board and specified in the project file config.c.
  2. 1ms periodic interrupt handler. This is installed in the generic 1ms interrupt list.

The initial version of the driver has separate vertical interrupt handler functions for each board. The appropriate handlers are assigned at driver installation using the function pointers passed via the configuration structures.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Dual Video Driver Font Loading

Text fonts are defined globally and are not specific to each video board. The font specifying functions therefore ignore the device parameter.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Multiplex Driver

The multiplex module is a device driver controlling the multiplexed lamps and seven segment displays. The Pluto 6 board has drives for 256 lamps in a 16x16 array and 32 7segment LED digits also in a 16x16 array with two digits on each strobe. Both arrays support variable 8 levels of brightness on an individual element basis.

API Functions

The following API functions are associated with this module:

Function | Description
Lamp | Sets the given lamp to the given status.
SetFlashTime | Sets the global lamp/LED flash time to the given value in 10ms units.
SetDefaultFlashTime | Restores the global lamp/LED flash time to its default value.
SetBrightness | Sets the lamp/LED brightness on the given strobe to the given value.
SetDefaultBrightness | Sets the lamp/LED brightness on all strobes to the default value.
LEDBits | Maps the 'bits' to the segment of the digit .

See Also

  • Multiplex Driver Configuration Data
  • Multiplex Driver Defined Values
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Lamp API Function

Multiplex Driver

API Function

void Lamp(const LAMP lamp, const STATUS status)

Description

Set the given lamp to the given status.

Parameters

Parameter | Description
lamp | Lamp to update
status | Lamp status

Return Value

None.

Code Example

/* declare a lamp */
LAMP lamp1;

/* Set the strobe/row for the lamp using the LAMP macro */
lamp1 = LAMP(LC1, LR1);

/* turn the defined lamp on */
Lamp(lamp1, ON);

© HEBER LTD. 2009. This document and the information contained therein is the intellectual
property of Heber Ltd. and must not be disclosed to a third party without consent. Copies
may be made only if they are in full and unmodified. The information contained in this
documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no
responsibility for its use, and reserves the right to revise the documentation without notice.

Document No: 80-17314, Issue 13    Release Date: 08.06.09
Email: support@heber.co.uk
www.heber.co.uk


Set Lamp Flash Time API Function

Multiplex Driver

API Function

void SetFlashTime(BYTE time)

Description

Set the global lamp/LED flash time to the given value in 10ms units. This time represents the duration of one phase of the fast flash.

Parameters

Parameter | Description
time | Flash time value

Return Value

None.

Code Example

/* Set the default flash time to 30ms */
SetFlashTime(3);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Restore Default Lamp Flash API Function

Multiplex Driver

API Function

void SetDefaultFlashTime()

Description

Restore the global lamp/LED flash time to its default value.

Parameters

None

Return Value

None

Code Example

/*Set the flash time to the default value */
SetDefaultFlashTime();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Lamp Brightness API Function

Multiplex Driver

API Function

void SetBrightness(WORD strobe, BYTE brightness)

Description

Set the lamp/LED brightness on the given strobe to the given value. The value should be in the range 0-255 although there are actually only 8 discrete levels.

Parameters

Parameter | Description
strobe | The strobe number whose brightness value is to be modified
brightness | The level of brightness

Return Value

None

Code Example

/* Set strobe 0 to half brightness */
SetBrightness(LC0, 128);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Default Brightness API Function

Multiplex Driver

API Function

void SetDefaultBrightness()

Description

Sets the lamp/LED brightness on all strobes to the default value.

Parameters

None

Return Value

None

Code Example

/* Set the level of brightness to the default value */
SetDefaultBrightness();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Map Bits API Function

Multiplex Driver

API Function

void LEDBits(DIGIT lp, UBYTE bits, STATUS status)

Description

The 'bits' are mapped to the segment of the digit such that segments corresponding to ones are set to the value of status and segments corresponding to zeros are set OFF.

Parameters

Parameter | Description
digit | LED to set to the defined status
bits | Bit mask for LED segments
status | LED status

Return Value

None.

Code Example

/* Set LED 1 segment A to fast flash */
LEDBits(LED1, SEG1, FF1);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Multiplex Driver Config Data

Multiplex Driver Configuration Data

The following data related to the Multiplex Driver is user configurable and is contained in the config.c file at game level.

The LAMPSCFG structure defines the default flash time (in increments of 10ms) and default brightness. These values apply to both the Lamps and the 7 Segment LEDs.

Example configuration

const LAMPSCFG LampsCfg=
{
8, /* Set default flash time to 80ms */
225 /* Set default brightness to maximum */
};

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Multiplex Driver Defined Values

The following values are defined for use with the Multiplex Driver:

Lamps Defined Values

Label | Meaning
LC0 - LC15 | Lamp columns 0 to 15
LR0 - LR15 | Lamp rows 0 to 15

Individual Lamp Definition

Label | Meaning
LAMP | The LAMP macro is used to define a particular lamp using a strobe and row reference. The LAMP type is a WORD value set using the LAMP macro.
EOF_LAMPS | Terminator used to mark the end of a list of individual lamps

Example of Use

/* define an array of lamps */
static const LAMP	lamp_array[]=
{
    LAMP(LC0,LR0),  /* lamp strobe 0, row 0 */
    LAMP(LC0,LR1),  /* lamp strobe 0, row 1 */
    LAMP(LC0,LR2),  /* lamp strobe 0, row 2 */
    EOF_LAMPS
};

Status defined values

Label | Meaning
ON | Set the lamp on
OFF | Set the lamp off
F1 | Set the lamp to flash
F2 | Set the lamp to flash in antiphase to F1
FF1 | Set the lamp to fast flash (fast flash is 4 times the rate of normal flash)
FF2 | Set the lamp to fast flash in antiphase to FF2

Example of Use

/* declare lamp pointer and status */
const	LAMP* lamp_ptr;
STATUS status;

/* set status to ON */
status = ON;

/* set lamp pointer to start of array of lamps */
lamp_ptr = lamp_array;

/* Set the level of brightness to the default value */
SetDefaultBrightness();

/* turn lamps on */
while(*lamp_ptr != EOF_LAMPS)
{
    Lamp(*lamp_ptr++, status);
}

7 Segment LED Defined Values

Label | Meaning
LED0 - LED15 | 7 Segment LEDs 0 -15

Label | Meaning
LED16 - LED31 | 7 Segment LEDs 16 -31

7 Segment LED mappings LED0 - LED31

Label | Bit | Mapping
SEG0 | 0 | Segment A
SEG1 | 1 | Segment B
SEG2 | 2 | Segment C
SEG3 | 3 | Segment D
SEG4 | 4 | Segment E
SEG5 | 5 | Segment F
SEG6 | 6 | Segment G
SEG7 | 7 | Point

Example of Use

/* set status to Flash */
status = F1;

/* Flash segment A on LED 8 */
LEDBits(LED8, SEG0, status);

Segment Naming Convention

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Multiplexed Inputs

The Multiplexed Inputs module is a device driver controlling system inputs. There are thirty-two system inputs. In their inactive state they are pulled up to +5v and read by the software as ‘1’ in this state. When the inputs are pulled down to ground they are read as ‘0’.

API Functions

The following API functions are associated with this module:

Function | Description
Test | Allows the status of a given input to be tested.
TestDir | Allows the status of a given input to be tested.
CurrentSense | Tests the current sense circuitry.
PushButton | Tests the state of the push button SW3.

See Also

  • MXI Configuration Data
  • MXI Defined Values
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Input Status API Function

Multiplexed Inputs Driver

API Function

BYTE Test(const INPUT input)

Description

This function allows the status of a given input to be tested. The inputs are read every N* milliseconds in an interrupt routine and a change of state registered after three consecutive reads that are the same. The function can also test inputs wired to one of the input strobes rather than zero volts.

Note: * N is the de-bounce sample time defined in the INPUTCFG structure at application level in config.c.

Parameters

Parameter | Description
input | The input to be tested. This will be one of the macros defining the Heber input numbers (IP0 - IP31)

Return Value

Return TRUE if the input is at its active state.
Return FALSE if the input is not at its active state.

Code Example

/* Test input number 20 */
if(Test(IP20))
{
    return(TRUE);
}

/*
Test the input number 20 with the input treated as active high. The function returns
TRUE when the input is inactive (read as 1)
*/
if(Test(ACT1 | IP20))
{
    return(TRUE);
}

/* test the input IP20 with reference to input strobe 0 */
if(Test(MXI0 | IP20))
{
    return(TRUE);
}

The outputs that are used as input strobes are defined in at game level in config.c in MxiStrobeLst[].

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


I/O Status API Function

Multiplexed Inputs Driver

API Function

BYTE TestDir(const INPUT ip);

Description

This function tests the I/O space directly and calculates its return value based on the instantaneous value read.

Parameters

Parameter | Description
input | The input to be tested. This will be one of the macros defining the Heber input numbers (IP0 - IP31)

Return Value

Return TRUE if the input is at its active state.
Return FALSE if the input is not at its active state.

Code Example

/* Test input IP20 */
if(TestDir(IP20))
{
    return(TRUE);
}

/*
Test the input number 20 with the input treated as active high.
The function returns TRUE when the input is inactive (read as 1)
*/
if(TestDir (ACT1 | IP20))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Current Sense API Function

Multiplexed Inputs Driver

API Function

BYTE CurrentSense()

Description

Test the current sense circuitry. This can be used to test for the presence of electro-mechanical counters.

Parameters

None

Return Value

Return TRUE if the current sense circuit is active. (i.e. current is flowing).
Return FALSE if the current is not flowing.

Code Example

/* Test for current flow */
if(CurrentSense())
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Push Button API Function

Multiplexed Inputs Driver

API Function

BYTE PushButton()

Description

Test the state of the push button SW3.

Parameters

None

Return Value

Return TRUE if the button is not depressed.
Return FALSE if the button is depressed.

Code Example

/* Test for button press */
if(PushButton())
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


MXI Config Data

MXI Configuration Data

The following data related to the Multiplexed Input Driver is user configurable and is contained in the config.c file at game level.

Debounce Sample Time

The sample time in milliseconds between each of the three reads when using debounced input reading can be set in the InputCfg structure:

const INPUTCFG InputCfg[]=
{
    {3}, /* Debounce sample time */
};

Strobe Input Memory Maps

For each input strobe defined a memory map needs to be defined. In the sample code below 2 memory maps are defined for 2 input strobes.

INPUTMAP	MxiInputMap[2];

Strobe Assignment

Any of the outputs (OP0 – OP63) can be allocated for use as input strobes. In the sample code below outputs OP62 and OP63 are defined as strobes for the multiplexed inputs.

const	WORD	MxiStrobeLst[]={OP63,OP62,-1};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


MXI Defined Values

The following values are defined for use with the Multiplexed Inputs Driver:

Label | Meaning
ACT0 | Active Low
ACT1 | Active High

Example of Use

/*
Test the input number 20 with the input treated as active high.
The function returns TRUE when the input is inactive (read as 1)
*/
if(Test(ACT1 | IP20))

{
    return(TRUE);
}

Label | Meaning
MXI0 | Multiplexed Strobe 0
MXI1 | Multiplexed Strobe 1
MXI2 | Multiplexed Strobe 2
MXI3 | Multiplexed Strobe 3

Example of Use

/* test the input IP20 with reference to input strobe 0 */
if(Test(MXI0 | IP20))
{
    return(TRUE);

}

Label | Meaning
IP0 - IP31 | Inputs 0 to 31

Example of Use

/* Test input number 20 */
if(Test(IP20))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Outputs Driver

The output module is a device driver controlling system outputs. There are 64 open drain outputs that are high impedance when inactive, and pulled down to ground when active. The status of all 64 outputs is maintained in RAM and written out to the I/O space every millisecond to give noise immunity.

API Functions

The following API functions are associated with this module:

Function | Description
OutputOn | Sets the status of the given output.
OutputOff | Sets the status of the given output.

See Also

  • Outputs Configuration Data
  • Outputs Defined Values
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Output On API Function

Outputs Driver

API Function

void OutputOn(const OUTPUT output)

Description

Sets the status of the given output to on (or active) in the status RAM. It is up to 1 millisecond before the output status is written out to the I/O space and the output pulled down to ground.

Parameters

Parameter | Description
output | The output to be asserted

Return Value

None.

Code Example

/* Assert output 24 */
OutputOn(OP24);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Outputs Off API Function

Outputs Driver

API Function

void OutputOff(const OUTPUT output)

Description

Sets the status of the given output to off (or inactive) in the status RAM. It is up to 1 millisecond before the output status is written out to the I/O space and the output goes into high impedance state.

Parameters

Parameter | Description
output | The output to be negated

Return Value

None.

Code Example

/* Negate output 24 */
OutputOff(OP24);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Outputs Config Data

Outputs Configuration Data

The following data related to the Outputs Driver is user configurable and is contained in the config.c file at game level.

Volatile Outputs List

Volatile outputs are those whose state is not restored on start up.

const	OUTPUT	VOPList[]={OP1, OP2, EOF_OUTPUTS};

Driver Configuration

The OUTPUTCFG structure allows the user to define a list of volatile outputs.

const	OUTPUTCFG	OutputCfg[]=
{
    {VOPList}
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Outputs Defined Values

The following values are defined for use with the Outputs Driver:

Label | Meaning
OP0 - OP63 | Outputs 0 to 63.

Example of Use

/* Assert output 12 */
OutputOn(OP12);

Label | Meaning
EOF_OUTPUTS | End of a list of outputs. Defined as -1.

Example of Use

/* define a list of outputs */
const OUTPUT outputs[]={OP0, OP1, OP2, OP3, OP4, OP5, EOF_OUTPUTS};

BYTE outputnumber = 0;

/* Turn on outputs in list */
while(outputs[outputnumber] != EOF_OUTPUTS)
{
    OutputOn(outputs[outputnumber]);
    Outputnumber++;
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Serial Communication Driver

Serial Communications Driver

The Serial Communications Driver contains wrapper functions to access the services of multiple serial devices available on the Pluto 6 control board.

Pluto 6 Serial Devices

The following standard serial devices are available on the Pluto 6 control board:

Device | Description
SerialDevice | Device driver for the two independent UARTs on the MCF5206e ColdFire® processor.
FPUART0Device | Device driver for FGPA UART 0.
FPUART1Device | Device driver for FPGA UART1.
DUART0Device | Device driver for the 68692 DUART optionally fitted in socket U56 on the Pluto 6 control board. This device has two UART channels.

Physical Output Connection

Each serial port can be routed to one of eight possible physical outputs. The available outputs are listed in Serial Device Defined Values.

Common Serial Device API Functions

The following API functions are common to all serial devices:

Function | Description
ConfigureSerial | Configures the receiver and transmitter for a given serial port.
TxChar | Transmits a character from the given port.
TxString | Transmits the character string from the given port.
RxChar | Transmit the character string from the given port.
TxEmpty | Tests the status of the transmit buffer for the given port.
RxEmpty | Tests the status of the receive buffer for the given port.
ClearTx | Clears the transmit buffer for the specified port.
ClearRx | Clears the receive buffer for the specified port.
SetRouting | Sets the routing for a given serial port.

FPGA UART API Functions

The two UART channels in the FPGA do not have hardware handshaking. However, handshaking is implemented in the software driver libraries. You can set the RTS level of the port that is currently connected to the UART, and also read the CTS level.

  • When the receiver is ready to receive, it will assert RTS. (setfpuartRTS(INCOMING_SERIAL))
  • When the transmitter sees a change in this signal (read CTS), it will start transmitting. (statusfpuartCTS(OUTCOMING_SERIAL))
  • This device will stop as soon as the receiver tells it to stop by changing the RTS level again. (clearfpuartRTS(INCOMING_SERIAL))

Note: The start and stop of the transmission is not controlled by the driver. This needs to be handled within your software code.

The following API functions are associated with the FPGA UART:

Function | Description
statusfpuartCTS | Returns the status of the FPGA UARTS CTS line.
clearfpuartRTS | Clears FPGA UART RTS line.
setfpuartRTS | Sets FPGA UART RTS line.

RS485 API Functions

The following API functions are associated with the RS485 serial communication:

Function | Description
EnableRS485Tx | RS485 Transmit enable signal.
DisableRS485Tx | RS485 Transmit disable signal.

Remarks

For a listing of the supported configuration settings that can be applied to the Pluto 6 serial ports refer to the Serial Device Defined Values.

The FPGA UARTs support a subset of the configuration options available on the ColdFire® UARTs and DUART. The configuration options for all serial devices are listed in the Serial Device Defined Values.

Attempting to install the DUART0 device driver without fitting a 68692 DUART chip into socket U56 will cause the Pluto 6 board to fail. For information on installing device drivers refer to the Installing Devices page.

See Also

  • Serial Communications Configuration Data
  • Serial Device Defined Values
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Transmit Buffer API Function

Serial Communications Driver

API Function

void ClearTx(const DEVICE* dev, BYTE channel);

Description

Clear the transmit buffer for the specified port.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use

Return Value

None

Code Example

/* Clear the transmit buffer for ColdFire UART 0 */
ClearTx(&SerialDevice, 0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Receive Buffer API Function

Serial Communications Driver

API Function

void ClearRx(const DEVICE* dev, BYTE channel);

Description

Clear the receive buffer for the specified port.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use

Return Value

None.

Code Example

/* Clear the receive buffer for FPGA UART 0 */
ClearRx(&FPUART0Device, 0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Transmit Character API Function

Serial Communications Driver

API Function

BYTE TxChar(const DEVICE* dev, BYTE channel, BYTE ch);

Description

Transmit a character from the given port.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use
ch | Channel within the device to use

Return Value

Return TRUE if the character has been placed in the transmit buffer.
Return FALSE if the buffer is full.

Code Example

/*
Wait until there is space in the FPGA UART 0 transmit buffer
then put 'M' in the buffer
*/
while(!TxChar(&FPUART0Device, 0, 'M'));
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Transmit String API Function

Serial Communications Driver

API Function

void TxString(const DEVICE* dev, BYTE channel, const BYTE* s);

Description

Transmit the character string from the given port. If necessary the function will wait for space in the transmit buffer before recommencing.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use
s | Address of the string to transmit

Return Value

None.

Code Example

/* Transmit a string using the ColdFire UART 1 */
TxString(&SerialDevice, 1, ”Transmit this string”);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Test Transmit API Function

Serial Communications Driver

API Function

BYTE TxEmpty(const DEVICE* dev, BYTE channel);

Description

Test the status of the transmit buffer for the given port.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use

Return Value

Return TRUE if the buffer is empty.
Return FALSE if there are characters awaiting transmission.

Code Example

/* wait for a character to be transmitted using the DUART device channel 0*/
while(!TxEmpty(&DUART0Device, 0));
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Test Rec Buff API Function

Serial Communications Driver

API Function

BYTE RxEmpty(const DEVICE* dev, BYTE channel);

Description

Test the status of the receive buffer for the given port.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use

Return Value

Return TRUE if the buffer is empty.
Return FALSE if there are characters waiting.

Code Example

/* wait for a character to arrive in the FPGA UART 1 device receive buffer*/
while(!RxEmpty(&FPUART1, 0));
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Routing API Function

Serial Communications Driver

API Function

void SetRouting(const DEVICE* dev, BYTE channel, BYTE route)

Description

Set the routing for a given serial port.

Remarks

Refer to the Serial Device Defined Values page for a list of the available routing options.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use
route | The route setting for the given serial port

Return Value

None.

Code Example

/* Route FPGA UART 0 to Pluto 6 RS232 */
SetRouting (&FPUART0Device, 0, RS232C);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Receive Character API Function

Serial Communications Driver

API Function

WORD RxChar(const DEVICE* dev, BYTE channel);

Description

Receive the character string from the given port. If necessary the function will wait for space in the transmit buffer before recommencing.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use
channel | Channel within the device to use

Return Value

Return the character received or –1 if the buffer is empty.

Code Example

/* Variable to hold received character */
WORD ch;

/* wait for a character to arrive in the DUART channel 1 RX buffer */
while((ch = RxChar(&DUART0Device, 1)) < 0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Configure API Function

Serial Communications Driver

API Function

void ConfigureSerial(const DEVICE* dev, BYTE channel, BYTE txbaud, BYTE rxbaud, BYTE data ,BYTE stop, BYTE parity, BYTE txhs , BYTE rxhs);

Description

Configure the receiver and transmitter for a given serial port. Supported values for port configuration settings are listed in the Serial Device Defined Values page.

Parameters

Parameter | Description
dev | Serial device to configure.
channel | Channel within the device to use.
txbaud | Transmitter Baud rate.
rxbaud | Receiver Baud rate.
data | Number of data bits per character.
stop | Number of stop bits.
parity | Parity setting.
txhs | Transmitter handshaking.
rxhs | Receiver handshaking.

Return Value

Returns TRUE if the serial port is successfully configured.

Code Example

/* Configure ColdFire UART A with the following settings:
    Transmitter Baud rate 9600
    Receiver Baud rate 9600
    8 data bits
    1 stop bit
    no parity
    no tx handshaking
    no rx handshaking
*/
ConfigureSerial(&SerialDevice, 0, BAUD9600, BAUD9600, BITS8, STOP1, PARITYNONE, TXNONE, RXNONE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FPGA UART API Function

Serial Communications Driver

API Function

statusfpuartCTS(const DEVICE* dev)

Description

Return the status of the FPGA UARTS CTS line.

Parameters

Parameter | Description
dev | Address of the UART device

Return Value

If the transmitter can read CTS it means that the receiver is now ready to receive.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FPGA UART API Function

Serial Communications Driver

API Function

void clearfpuartRTS(const DEVICE* dev)

Description

Clear FPGA UART RTS line - Receiver not ready.

Parameters

Parameter | Description
dev | Address of the UART device.

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FPGA UART API Function

Serial Communications Driver

API Function

void setfpuartRTS(const DEVICE* dev)

Description

Set FPGA UART RTS line - Receiver ready.

Parameters

Parameter | Description
dev | Address of the device driver for the serial device to use.

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


RS485 API Function

Serial Communications Driver

API Function

void EnableRS485Tx(const DEVICE* device)

Description

RS485 TRANSCEIVER must be fitted to socket U41 for RS485 functionality. When ColdFire UART Control Register bit 7is set to 1, RS485 Transmit enable signal is sent to U41.

Parameters

Parameter | Description
device | Address of device (not used for now).

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


RS485 API Function

Serial Communications Driver

API Function

void DisableRS485Tx(const DEVICE* device)

Description

RS485 TRANSCEIVER must be fitted to socket U41 for RS485 functionality. When ColdFire UART Control Register bit 7is set to 0, RS485 Transmission is disabled.

Parameters

Parameter | Description
device | Address of device (not used for now).

Return Value

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Serial Comms Config Data

Serial Communications Configuration Data

The following data related to the Serial Device Drivers is user configurable and is contained in the config.c file at game level.

ColdFire UART Data Buffers and Configuration

The following receive and transmit data buffers are declared for use with the ColdFire UARTs:

/* Transmit and receive buffers */
BYTE SerialModTxABuffer[1<<4]={0};	/* Channel A transmit buffer */
BYTE SerialModRxABuffer[1<<4]={0};	/* Channel A receive buffer */
BYTE SerialModTxBBuffer[1<<4]={0};	/* Channel B transmit buffer */
BYTE SerialModRxBBuffer[1<<4]={0};	/* Channel B receive buffer */

/* Masks defining the size of the buffers */
const WORD SerialModTxAMask=sizeof(SerialModTxABuffer)-1;
const WORD SerialModRxAMask=sizeof(SerialModRxABuffer)-1;
const WORD SerialModTxBMask=sizeof(SerialModTxBBuffer)-1;
const WORD SerialModRxBMask=sizeof(SerialModRxBBuffer)-1;

The SERIALCFG structure defines the hardware settings for the ColdFire UARTs and the default port configuration settings:

const SERIALCFG SerialModuleCfg[] =
{
    0xDD,	/* status register channel A */
    0x03, /* interrupt mask register channel A */
    0x50, /* interrupt vector register channel A */
    0xDD,	/* status register channel B */
    0x03,	/* interrupt mask register channel B */
    0x51,	/* interrupt vector register channel B */
    /* Channel A default configuration */
    BAUD9600,BAUD9600,BITS8,STOPBITS,PARITYNONE,TXNONE,RXNONE,
    /* Channel B default configuration */
    BAUD9600,BAUD9600,BITS8,STOPBITS,PARITYNONE,TXNONE,RXNONE
};

FPGA UART 0 Data Buffers and Configuration

The following receive and transmit data buffers are declared for use with FPGA UART 0:

/* Transmit and receive buffers */
BYTE FPuart0TxBuffer[1<<4]={0};
BYTE FPuart0RxBuffer[1<<4]={0};

The FPUARTCFG structure defines the configuration settings for the FPGA UARTs:

const FPUARTCFG FPUART0Cfg[]=
{
    (void*)FPGA_UART0_BASE,		/* Device base address */
    FPuart0ISR,				/* Service routine */
    FPuart0TxBuffer,			/* Transmit buffer */
    FPuart0RxBuffer,			/* Receive buffer */
    sizeof(FPuart0TxBuffer)-1,		/* Transmit buffer size */
    sizeof(FPuart0RxBuffer)-1,		/* Receive buffer size */
};

FGPA UART 1 Data Buffers and Configuration

The following receive and transmit data buffers are declared for use with FPGA UART 1:

/* Transmit and receive buffers */
BYTE	FPuart1TxBuffer[1<<4]={0};
BYTE	FPuart1RxBuffer[1<<4]={0};

The FPUARTCFG structure defines the configuration settings for the FPGA UARTs:

const	FPUARTCFG	FPUART1Cfg[]=
{
    (void*)FPGA_UART1_BASE,		/* Device base address */
    FPuart1ISR,				/* Service routine */
    FPuart1TxBuffer,			/* Transmit buffer */
    FPuart1RxBuffer,			/* Receive buffer */
    /* Transmit and receive buffer sizes */
    sizeof(FPuart1TxBuffer)-1,
    sizeof(FPuart1RxBuffer)-1,
};

DUART Data Buffers and Configuration

The following receive and transmit data buffers are declared for use with the DUART:

/* Transmit and receive buffers */
static BYTE Duart0TxABuffer[1<<4]={0};
static BYTE Duart0RxABuffer[1<<4]={0};
static BYTE Duart0TxBBuffer[1<<4]={0};
static BYTE Duart0RxBBuffer[1<<4]={0};

The DUARTCFG structure defines the configuration settings for the DUART:

const	DUARTCFG	DUART0Cfg[]=
{
    {
        DUART0BASE, 	/* Base address */
        Duart0ISR,		/* Service routine */
        Duart0TxABuffer,	/* TX buffer channel A */

        Duart0RxABuffer,	/* RX buffer channel A */
        Duart0TxBBuffer,	/* TX buffer channel B */
        Duart0RxBBuffer,	/* RX buffer channel B */
        /* Receive and transmit buffer sizes */
        sizeof(Duart0TxABuffer)-1,
        sizeof(Duart0RxABuffer)-1,
        sizeof(Duart0TxBBuffer)-1,
        sizeof(Duart0RxBBuffer)-1,

        /* Channel A default configuration */
        BAUD9600,BAUD9600,BITS8,STOP1,PARITYNONE,TXNONE,RXNONE,
        /* Channel B default configuration */
        BAUD9600,BAUD9600,BITS8,STOP1,PARITYNONE,TXNONE,RXNONE

    }

    {
    0,
    0
    }
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Serial Device Defined Values

The following values are defined for use with the Pluto 6 serial communications device drivers.

Baud Rates

The following defined Baud rates are valid for the ColdFire® UARTs (SerialDevice) and DUART (DUART0Device):

Label | Baud Rate
BAUD50 | 50
BAUD75 | 75
BAUD110 | 110
BAUD134 | 134
BAUD150 | 150
BAUD200 | 200
BAUD300 | 300
BAUD600 | 600
BAUD1050 | 1050
BAUD1200 | 1200
BAUD1800 | 1800
BAUD2000 | 2000
BAUD2400 | 2400
BAUD4800 | 4800
BAUD7200 | 7200
BAUD9600 | 9600
BAUD19200 | 19200
BAUD38400 | 38400
BAUD76800 | 76800

The following defined Baud rates are valid for the FPGA UARTs (FPUART0Device and FPUART1Device):

Label | Baud Rate
BAUD1200 | 1200
BAUD2400 | 2400
BAUD4800 | 4800
BAUD9600 | 9600
BAUD19200 | 19200

In addition to the Baud rates stated above, following defined Baud rates are available for the DUART UARTs (DUART0Device):

Label | Baud Rate
BRG_TEST_57600 | 57600
BRG_TEST_115200 | 115200

NOTE: To use Baud rates of 57600 or 115200 the DUART device must be put into BRG_TEST mode. In this mode standard Baud rates are not available. If either 57600 or 115200 are selected both UARTS are set to this rate and can not be independently configured. The Baud rate is applied to both receiver and transmitter.

Data Bits

The following defined numbers of data bits per character are valid for the ColdFire® UARTs (SerialDevice) and DUART (DUART0Device):

Label | Setting
BITS6 | 6 data bits
BITS7 | 7 data bits
BITS8 | 8 data bits

The following defined numbers of data bits per character are valid for the FPGA UARTs (FPUART0Device and FPUART1Device):

Label | Setting
BITS7 | 7 data bits
BITS8 | 8 data bits

Stop Bits

The following defined numbers of stop bits are valid for all serial devices:

Label | Setting
STOP1 | 1 stop bit
STOP2 | 2 stop bit

Parity Setting

The following defined parity settings are valid for all serial devices:

Label | Setting
PARITYEVEN | Even parity
PARITYODD | Odd parity
PARITYNONE | No parity

Handshaking

These settings only apply for ColdFire® UARTs and DUART0Device.

The following are permitted values:

Label | Setting
TXRTS | RTS handshake
TXCTS | CTS handshake
TXNONE | No handshake

Routing Options

The following defined routing options are valid for all serial devices:

Label | Setting | Connector
BACTA | Dataport | P22
RS232A | RS232 | P21
RS232C | RS232 | P21
RS232D | RS232 | P21
CCTALK1 | CCTALK | P20
CCTALK2 | CCTALK | P20
TTL | TTL | P23
RS485 | RS485 | P23

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pic18 Driver

The PIC18 driver module provides functions to access data on the PIC18 Customer Security Device fitted into socket U5 on the Pluto 6 controller board. Communication with the PIC18 uses the I²C protocol provided by the M-Bus driver module.

API Functions

The following API functions are associated with this module:

Function | Description
GetPIC18Time | Reads the data from the real time clock on the PIC18 Customer Security Device.
GetPIC18TimeFine | Reads the fine granularity data from the real time clock on the PIC18 Customer Security Device, providing resolution to 1/100ths of a second.
SetPIC18Time | Sets the real time clock on the PIC18 Customer Security Device to the time/date setting specified.
GetPIC18Log | Reads a specified entry in the PIC18 security log.
ClearPIC18Log | Clears all entries in the PIC18 security log.
GetPIC18Percent | Reads the percentage key data from the PIC18 security device.
GetPIC18Stake | Reads the stake/jackpot key data from the PIC18 security device.
GetPIC18Dil1 | Reads the switch setting for DIL switch 1 from the PIC18 security device.
GetPIC18Dil2 | Reads the switch setting for DIL switch 2 from the PIC18 security device.
GetPIC18Revision | Reads the software revision number from the PIC18 security device.

See Also

  • PIC18 Customer Security Device Configuration Data
  • PIC18 Customer Security Device Data Types
  • PIC18 Customer Security Data Representation
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Time API Function

PIC18 Driver

API Function

BYTE GetPIC18Time(const DEVICE* picdev, P18TIME* picrtctime)

Description

Read the data from the real time clock on the PIC18 Customer Security Device.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.
picrtctime | Address of the formatted time structure to store the clock reading in.

Return Value

Return TRUE if the clock is read successfully.
Return FALSE if the clock read fails.

Code Example

/* define a time structure */
P18TIME picrtctime;

/* Get the current real time clock reading */
GetPIC18Time(&PICDevice, &picrtctime);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Time API Function

PIC18 Driver

API Function

BYTE SetPIC18Time(const DEVICE* picdev, const P18TIME* time)

Description

Set the real time clock on the PIC18 Customer Security Device to the time/date setting specified.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.
time | Address of the formatted time structure which contains the clock time setting.

Return Value

Return TRUE if the time data is successfully written to the real time clock.
Return FALSE if the operation fails.

Code Example

/* declare a time structure */
P18TIME time;

/* Set the data in the time structure to midday on 25 December 2005 */
time.year = 2005;
time.month = 12;
time.date = 25;
time.hours = 12;
time.minutes = 0;
time.seconds = 0;
time.hundredths = 0;

/* Set the real time clock to the specified time */
SetPIC18Time(&PICDevice, &time);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Fine Granularity Time API Function

PIC18 Driver

API Function

BYTE GetPIC18TimeFine(const DEVICE* picdev, P18TIME* picrtctime)

Description

Read the fine granularity data from the real time clock on the PIC18 Customer Security Device, providing 1/100ths of a second clock resolution. On Pluto 6 boards with CSDs that have the enhanced real time clock, this function will retrieve the time in seconds in the same manner as GetPIC18Time, but will also populate the hundredths member of the P18TIME structure correctly.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.
picrtctime | Address of the formatted time structure to store the clock reading in.

Return Value

Return TRUE if the clock is read successfully.
Return FALSE if the clock read fails.

Code Example

/* define a time structure */
P18TIME picrtctime;

/* Get the current real time clock reading */
GetPIC18TimeFine(&PICDevice, &picrtctime);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Security Entry API Function

PIC18 Driver

API Function

BYTE GetPIC18Log(const DEVICE* picdev, BYTE logindex, P18TIME* picrtctime, BYTE* pwroffinput)

Description

Read a specified entry in the PIC18 security log. The PIC holds 10 records that can be accessed using a log index value in the range 1 to 10. If the GetPIC18Log() function is called using a log index value outside the specified range the function will return ERR_WRONG_INDEX.

Remarks

For information on the format of a security log record entry refer to the PIC18 CSD Data Representation page.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.
logindex | Entry number in the PIC18 security log to read.
picrtctime | Address of the formatted time structure to store the switch log time data.
pwroffinput | Address to store the switch status data at the time that switches last changed.

Return Value

Return TRUE if the clock is read successfully.
Return ERR_WRONG_INDEX if the log index is outside the range 1-10.
Return ERR_RECORD_EMPTY if the specified log contains no security switch change entry.
Return ERR_MBUS_FAIL if the clock read fails.

Code Example

/* declare a time structure to hold the log entry time stamp */
P18TIME time;
/* declare a  variable to hold the log entry switch status */
BYTE 	inputreading;
BYTE	return_code;

/* Read log entry and time stamp from location 5 in the log */
return_code = GetPIC18Log(&PICDevice, 5, &time, &inputreading)

switch(return_code)
{
    case TRUE:
        return(TRUE);
        break;
    case ERR_MBUS_FAIL:
        TxString(serialdevice,channel,"problem communication with pic try again\r");
        break;
    case ERR_RECORD_EMPTY:
        sprintf(str, "no entry for %d \r ", logindex);
        TxString(serialdevice,channel,str);
        break;
    case ERR_WRONG_INDEX:
        TxString(serialdevice,channel,"wrong index! \r");
        break;
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Dil Switch 1 API Function

PIC18 Driver

API Function

BYTE GetPIC18Dil1(const DEVICE* picdev, BYTE* dil1data)

Description

Read the switch setting for DIL switch 1 from the PIC18 security device.

Remarks

For information on the format of the DIL switch data refer to the PIC18 CSD Data Representation page.

Parameters

Parameter | Description
picdev | Address of the PIC18 device
dil1data | Address to store DIL switch 1 reading

Return Value

Return TRUE if the switch data is successfully read.
Return FALSE if the operation fails.

Code Example

/* declare a  variable to hold the DIL switch 1 reading */
BYTE dil1data;

/* read the DIL switch 1 data */
if(GetPIC18Dil1(&PICDevice, &dil1data))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Dil Switch 2 API Function

PIC18 Driver

API Function

BYTE GetPIC18Dil2(const DEVICE* picdev, BYTE* dil2data)

Description

Read the switch setting for DIL switch 2 from the PIC18 security device.

Remarks

For information on the format of the DIL switch data refer to the PIC18 CSD Data Representation page.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.
dil2data | Address to store DIL switch 2 reading.

Return Value

Return TRUE if the switch data is successfully read.
Return FALSE if the operation fails.

Code Example

/* declare a  variable to hold the DIL switch 2 reading */
BYTE dil2data;

/* read the DIL switch 2 data */
if(GetPIC18Dil2(&PICDevice, &dil2data))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Entry API Function

PIC18 Driver

API Function

BYTE ClearPIC18Log(const DEVICE* picdev)

Description

Clear all entries in the PIC18 security log. After the log has been cleared the security switch status is read and stored as a global variable within the PIC. This variable will be used to detect a change within the switches. Only a change will trigger the PIC to record a new switch reading into the log. This way of handling the recording saves one entry within the LOG.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.

Return Value

Return TRUE if the log is successfully cleared.
Return FALSE if the operation fails.

Code Example

/* clear all of the entries in the security switch log */
if(ClearPIC18Log(&PICDevice))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Percent API Function

PIC18 Driver

API Function

BYTE GetPIC18Percent(const DEVICE* picdev, BYTE* percentdata)

Description

Read the percentage key data from the PIC18 security device.

Remarks

For information on the format of the percentage data refer to the PIC18 CSD Data Representation page.

Parameters

Parameter | Description
picdev | Address of the PIC18 device
percentdata | Address of the formatted time structure which contains the clock time setting

Return Value

Return TRUE if the percentage data is successfully read.
Return FALSE if the operation fails.

Code Example

/* declare a  variable to hold the percentage key reading */
BYTE 	percentdata;

/* read the percentage key data */
if(GetPIC18Percent(&PICDevice, &percentdata))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Stake API Function

PIC18 Driver

API Function

BYTE GetPIC18Stake(const DEVICE* picdev, BYTE* stakedata)

Description

Read the stake/jackpot key data from the PIC18 security device.

Remarks

For information on the format of the stake data refer to the PIC18 CSD Data Representation page.

Parameters

Parameter | Description
picdev | Address of the PIC18 device.
stakedata | Address to store stake/jackpot data reading.

Return Value

Return TRUE if the stake/jackpot data is successfully read.
Return FALSE if the operation fails.

Code Example

/* declare a  variable to hold the stake key reading */
BYTE 	stakedata;

/* read the stake key data */
if(GetPIC18Stake(&PICDevice, &stakedata))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Revision Number API Function

PIC18 Driver

 IMG ALIGN="RIGHT" SRC="../../../../images/pluto_small.jpg">

API Function

BYTE GetPIC18Revision(const DEVICE* picdev, BYTE* revisiondata)

Description

Read the software revision number from the PIC18 security device.

Parameters

Parameter | Description
picdev | Address of the PIC18 device
revisiondata | Address to store the revision number reading

Return Value

Return TRUE if the revision number is successfully read.
Return FALSE if the operation fails.

Code Example

/* declare a  variable to hold revision number */
BYTE 	revisiondata;

/* read the revision number */
if(GetPIC18 Revision(&PICDevice, &revisiondata))
{
    return TRUE;
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


PIC18 CSD Config Data

PIC18 Customer Security Device Driver Configuration Data

The PIC18CFG structure in the file config.c defines the I²C driver that the PIC18 device uses for communication and the I²C hardware address that is assigned to the PIC18 device. The default configuration uses the M-Bus I²C device driver and the I²C hardware address 0xC0.

const PIC18CFG	PIC18Cfg[]=
{
    {
        &MbusDevice,		/* M-Bus I2C Device Driver */
         0xC0			/* I2Caddress = C0 */
    }
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


PIC18 CSD Data Types

PIC18 Customer Security Device Data Types

PIC18 Time Data Structure

This structure is used to store the formatted real time clock data read from the PIC18.

typedef struct pic18time
{
    WORD	year;
    BYTE	month;
    BYTE	weekday;
    BYTE	date;
    BYTE	hours;
    BYTE	minutes;
    BYTE	seconds;
    BYTE	hundredths;
} P18TIME;

Example of Use

/* define a time structure */
P18TIME 	picrtctime;

/* Get the current real time clock reading */
GetPIC18Time(&PICDevice, &picrtctime);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


PIC18 CSD Data Representation

PIC18 Driver Data Representation

In each API function that reads data from the PIC18 the returned data represents the following information:

GetPIC18Log( )

The pwroffinput BYTE is used to represent the position of the security switches when the log entry was made.

pwroffinput BYTE
Not Used |  |  |  | Switch 3 | Switch 2 | Switch 1 | Switch 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
Not Used |  |  |  | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON

Code Example

/* byte to store switch reading */
BYTE pwroffinput;
/* time structure to store switch log entry timestamp */
P18TIME picrtctime;

/* Read switch log entry 1 */
if(GetPIC18Log(&PICDevice, 1, &picrtctime, &pwroffinput))
{
    /* Read successful and entry contains data */
    if(pwroffinput & 0x01)
    {
        /* switch 1 was on at the time of the log entry */
        return(TRUE);
    }
}

GetPIC18Percent( )

The percentdata BYTE is used to represent the reading of a percentage key connected to the Pluto 6 board.

percentdata BYTE
Not Used |  |  |  | Position 3 | Position 2 | Position 1 | Position 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
Not Used |  |  |  | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set

Code Example

/* byte to store percentage key reading */
BYTE percentdata;

/* Read percentage key */
if(GetPIC18Percent(&PICDevice, &percentdata))
{
    /* key read successful */
    return(TRUE);
}

GetPIC18Stake( )

The stakedata BYTE is used to represent the reading of a stake/jackpot key connected to the Pluto 6 board.

stakedata BYTE
Not Used | Stake 2 | Stake 1 | Stake 0 | Jackpot 3 | Jackpot 2 | Jackpot 1 | Jackpot 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
Not Used | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set | 0=Not Set 1=Set

Code Example

/* byte to store percentage key reading */
BYTE stakedata;

/* Read stake/jackpot key */
if(GetPIC18Stake(&PICDevice, &stakedata))
{
    /* key read successful */
    return(TRUE);
}

GetPIC18Dil1( )

The dil1data BYTE is used to represent the reading of DIL switch 1 (switch SW1) on the Pluto 6 board.

dil1data BYTE
Switch 7 | Switch 6 | Switch 5 | Switch 4 | Switch 3 | Switch 2 | Switch 1 | Switch 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON

Code Example

/* byte to store DIL switch 1 reading */
BYTE	dil1data;

/* Read DIL switch 1 data */
if(GetPIC18Dil1(&PICDevice, & dil1data))
{
    /* switch read successful */
    return TRUE;
}

GetPIC18Dil2( )

The dil1data BYTE is used to represent the reading of DIL switch 2 (switch SW2) on the Pluto 6 board.

dil2data BYTE
Switch 7 | Switch 6 | Switch 5 | Switch 4 | Switch 3 | Switch 2 | Switch 1 | Switch 0
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON | 0=OFF 1=ON

Code Example

/* byte to store DIL switch 2 reading */
BYTE dil2data;

/* Read DIL switch 2 data */
if(GetPIC18Dil2(&PICDevice, & dil2data))
{
    /* switch read successful */
    return TRUE;
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


M-Bus Driver

The M-Bus driver implements an I²C interface using the Motorola ColdFire® M-Bus module. The M-Bus driver can be used to access an external I²C device using connector P27 on the Pluto 6 board.

API Functions

The following API functions are associated with this module:

Function | Description
MbusWrite | Writes a specified number of bytes of data to the given internal address on the specified I²C device.
MbusRead | Reads a specified number of bytes of data from the given internal address on the specified I²C device.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Write Bytes API Function

M-Bus Driver

API Function

BYTE MbusWrite(const BYTE* source, LONG bytecount, BYTE deviceaddress, BYTE internaladdress)

Description

Write a specified number of bytes of data to the given internal address on the specified I²C device.

Parameters

Parameter | Description
source | Address of the source data.
bytecount | Number of bytes to be written.
deviceaddress | Hardware address of the I²C device to be written to.
internaladdress | Internal address on the I²C device where the data is to be written to.

Return Value

Return TRUE if the write is successful.
Return FALSE if the write fails.

Code Example

/*
Write 4 bytes of data from buffer src to an I²C device with hardware address
0xD0 and internal address 0x0A
*/
if(MbusWrite(&src, 4 0xD0, 0x0A))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Bytes API Function

M-Bus Driver

API Function

BYTE MbusRead(BYTE deviceaddress, BYTE internaladdress, BYTE *dst, LONG bytecount)

Description

Read a specified number of bytes of data from the given internal address on the specified I²C device.

Parameters

Parameter | Description
deviceaddress | Hardware address of the I²C device to be read from.
internaladdress | Internal address on the I²C device where the data is to be read from.
dst | Address where the read data will be stored.
bytecount | Number of bytes to be read.

Return Value

Return TRUE if the read is successful.
Return FALSE if the read fails.

Code Example

/*
Read 7 bytes of data from internal address 0x0A in an I²C device with hardware address
0xD0 and store data in buffer dst
*/
if(MbusRead(0xD0, 0x0A &dst, 7))
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


VFD Driver

Vacuum Fluorescent Display Driver

The Vacuum Fluorescent Display (VFD) module is a service module providing low level functions for addressing vacuum fluorescent displays. The system is capable of driving two VFDs from the Auxiliary Output connector P15 on the Pluto 6 board. Two structures, Vfd1 and Vfd2, found in config.c in the game directory allow the mapping of VFD control signals to output pins.

API Functions

The following API functions are associated with this module:

Function | Description
TxVFD1 | Sends a character to VFD1.
ResetVFD1 | Resets the VFD display.
TxVFD2 | Sends a character to VFD2
ResetVFD2 | Resets the VFD display.

See Also

  • VFD Configuration Data
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Reset VFD1 API Function

VFD Driver

API Function

void ResetVFD1()

Description

Reset the VFD display. The reset line is asserted for the time defined in the vfd1 structure in config.c.

Parameters

None.

Return Value

None.

Code Example

/* Reset VFD 1*/
ResetVFD1( );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Reset VFD2 API Function

VFD Driver

API Function

void ResetVFD2()

Description

Reset the VFD display. The reset line is asserted for the time defined in the vfd2 structure in config.c

Parameters

None.

Return Value

None.

Code Example

/* Reset VFD 2*/
ResetVFD2( );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


TXVFD1 API Function

VFD Driver

API Function

void TxVFD1(BYTE ch)

Description

Send a character to VFD1.

Parameters

Parameter | Description
ch | Character to send to the VFD.

Return Value

None.

Code Example

/* Send byte value 0x41 (ascii A) to VFD1 */
TxVFD1(0x41);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


TXVFD2 API Function

VFD Driver

API Function

void TxVFD2(BYTE ch)

Description

Send a character to VFD2.

Parameters

Parameter | Description
ch | Character to send to the VFD.

Return Value

None.

Code Example

/* Send byte value 0x43 (ascii C) to VFD2 */
TxVFD2(0x43);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


VFD Config Data

VFD Configuration Data

The following two structures, VFD1 and VFD 2, related to the VFD Device Drivers is user configurable and is contained in the config.c file at game level.

/* VFD 1 */
const VFD Vfd1=
{
    (UBYTE*)AUX0, /* Clock line mapped to Auxiliary Output 0*/
    (UBYTE*)AUX1, /* Data line mapped to Auxiliary Output 1 */
    (UBYTE*)AUX2, /* Reset line mapped to Auxiliary Output 2 */
    3000, /* Reset delay */
    200 /* Inter-byte delay */
};

/* VFD 2 */
const VFD Vfd2=
{
     (UBYTE*)AUX3, /* Clock line mapped to Auxiliary Output 3*/
     (UBYTE*)AUX4, /* Data line mapped to Auxiliary Output 4 */
     (UBYTE*)AUX5, /* Reset line mapped to Auxiliary Output 5 */
     3000, /* Reset delay */
     200 /* Inter-byte delay */
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


ATA Driver

The ATA driver provides the low-level interface functions to access data from an ATA hard disk or Compact Flash storage device. The Pluto 6 provides the following physical connections for these devices; IDE connector (P5) to connect a hard disk, and Compact Flash connector (P6) the connect a Compact Flash card.

API Functions

The following API functions are associated with this module:

Function | Description
ReadDriveID | Reads the drive information from the ATA device.
GetDriveModel | Gets the drive model data from the drive information structure populated by the ReadDriveID( ) function.
GetDriveRev | Gets the drive revision data from the drive information structure populated by the ReadDriveID( ) function.
GetDriveSerialno | Gets the drive serial number from the drive information structure populated by the ReadDriveID( ) function.
GetDriveCyls | Gets the number of cylinders in the drive from the drive information structure populated by the ReadDriveID( ) function.
GetDriveHeads | Gets the number of heads in the drive from the drive information structure populated by the ReadDriveID( ) function.
GetDriveSectors | Gets the number of sectors in the drive from the drive information structure populated by the ReadDriveID( ) function.
DriveSpinup | Powers up the motor on a hard drive device.
DriveSpindown | Powers down the motor on a hard drive device.
ReadSectors | Reads a specified number of sectors from an ATA device.
WriteSectors | Writes a single sector to an ATA device at a given address.

See Also

  • ATA Configuration Data
  • ATA Defined Values
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Drive Spin Up API Function

ATA Driver

API Function

ATASTS DriveSpinup( )

Description

Powers up the motor on a hard drive device. If a hard drive has been powered down during a period of inactivity a read from the drive will cause the hard drive motor to be powered up automatically. It should be noted that it will take between 1 and 2 seconds for the drive motor to reach operating speed. The DriveSpinup( ) function can be used in advance of the read operation to ensure that the drive is at operating speed.

Parameters

None.

Return Value

Returns ATA_OK if the drive motor is successfully powered up.
Returns BSY_TIMEOUT if the drive is busy and a timeout occurs.

Code Example

/* Power up the ATA hard drive */
if(DriveSpinUp( ) == ATA_OK)
{
    return(TRUE);
}
else
{
    return(FALSE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Drive Spin Down API Function

ATA Driver

API Function

ATASTS DriveSpindown( )

Description

Powers down the motor on a hard drive device. This function can be used to stop the motor on a hard drive during periods of inactivity.

Parameters

None.

Return Value

Returns ATA_OK if the drive motor is successfully powered down.
Returns BSY_TIMEOUT if the drive is busy and a timeout occurs.

Code Example

/* Power down the ATA hard drive */
if(DriveSpinDown( ) == ATA_OK)
{
    return(TRUE);
}
else
{

    return(FALSE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Drive Sectors API Function

ATA Driver

API Function

UWORD GetDriveSectors( )

Description

Gets the number of sectors on the drive from the drive information structure populated by the ReadDriveID( ) function. The ReadDriveID( ) function must be called once before the GetDriveSectors( ) function is called to ensure that the drive information structure contains valid data.

Parameters

None.

Return Value

Returns the number of sectors in the drive.

Code Example

/* declare a variable to store the number of drive sectors */
UWORD sectors;

/* get the number of sectors from the drive */
sectors = GetDriveSectors();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Drive Heads API Function

ATA Driver

API Function

UWORD GetDriveHeads( )

Description

Gets the number of heads on the drive from the drive information structure populated by the ReadDriveID( ) function. The ReadDriveID( ) function must be called once before the GetDriveHeads( ) function is called to ensure that the drive information structure contains valid data.

Parameters

None.

Return Value

Returns the number of heads in the drive.

Code Example

/* declare a variable to store the number of drive heads */
UWORD heads;

/* get the number of heads from the drive */
heads = GetDriveHeads();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Sectors API Function

ATA Driver

API Function

ATASTS ReadSectors( ULONG lba, UWORD *buffer, UBYTE count)

Description

Read a specified number of sectors from an ATA device starting from a given sector and store the data read in memory starting at a specified address.

Parameters

Parameter | Description
lba | Logical block address of the sector to begin reading from.
buffer | Start address in memory to store the data read from the ATA device.
count | Number of sectors to read from the ATA device.

Return Value

Returns ATA_OK if the specified sectors are read successfully.
Returns BSY_TIMEOUT if the drive is busy and a timeout occurs.

Code Example

/* 28 bit Logical Block */
ULONG lba;

/* buffer to store sector read from the ATA device */
UWORD sector_buffer[256];

/* logical block address 0 */
lba = 0;

/* read 1 sector from lba 0 to sector buffer */
if(ReadSectors(lba, sector_buffer, 1) == ATA_OK)
{
    return(TRUE);
}
else
{
    return(FALSE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Write Sectors API Function

ATA Driver

API Function

ATASTS WriteSectors(const DEVICE *dev, ULONG lba, UWORD *buffer)

Description

Write a single sector to an ATA device at a given address. Read the data to be written from a specified address.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
lba | Logical block address of the sector to write to.
buffer | Start address in memory of the data to write to the ATA device.

Return Value

Returns ATA_OK if the sector was written successfully.
Returns BSY_TIMEOUT if the drive is busy and a timeout occurs.

Code Example

/* 28 bit Logical Block */
ULONG lba;

/* buffer to contain data to write to the ATA device */
UWORD sector_buffer[256];

/* logical block address 0 */
lba = 0;

/* fill buffer with useful data…*/

/* write the buffer to lba 0 of the ata device  */
if(WriteSectors(&ATADevice, lba, sector_buffer) == ATA_OK)
{
    return(TRUE);
}
else
{
    return(FALSE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Drive Model API Function

ATA Driver

API Function

UBYTE* GetDriveModel( )

Description

Gets the drive model data from the drive information structure populated by the ReadDriveID( ) function. The ReadDriveID( ) function must be called once before the GetDriveModel( ) function is called to ensure that the drive information structure contains valid data.

Parameters

None.

Return Value

Returns a UBYTE pointer to start of the NULL terminated string containing the drive model information.

Code Example

/* declare pointer for the model number */
BYTE * modelstring;

/* get the drive model information */
modelstring = GetDriveModel();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Drive Rev API Function

ATA Driver

API Function

UBYTE* GetDriveRev( )

Description

Gets the drive revision data from the drive information structure populated by the ReadDriveID( ) function. The ReadDriveID( ) function must be called once before the GetDriveRev( ) function is called to ensure that the drive information structure contains valid data.

Parameters

None.

Return Value

Returns a UBYTE pointer to start of the NULL terminated string containing the drive revision information.

Code Example

/* declare pointer for the drive revision */
BYTE * revisionstring;

/* get the drive revision information */
revisionstring = GetDriveRev();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Drive Cylinders API Function

ATA Driver

API Function

UWORD GetDriveCyls( )

Description

Gets the number of cylinders in the drive from the drive information structure populated by the ReadDriveID( ) function. The ReadDriveID( ) function must be called once before the GetDriveCyls( ) function is called to ensure that the drive information structure contains valid data.

Parameters

None.

Return Value

Returns the number of cylinders in the drive.

Code Example

/* declare a variable to store the number of drive cylinders */
UWORD cylinders;

/* get the number of cylinders from the drive */
cylinders = GetDriveCyls();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Drive Serial No. API Function

ATA Driver

API Function

UBYTE* GetDriveSerialno( )

Description

Gets the drive serial number from the drive information structure populated by the ReadDriveID( ) function. The ReadDriveID( ) function must be called once before the GetDriveSerialno( ) function is called to ensure that the drive information structure contains valid data.

Parameters

None.

Return Value

Returns a UBYTE pointer to start of the NULL terminated string containing the drive serial number.

Code Example

/* declare pointer for the drive serial number */
BYTE * serialstring;

/* get the drive serial number */
serialstring = GetDriveSerialno();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read Drive API Function

ATA Driver

API Function

ATASTS ReadDriveID( )

Description

Read the drive information from the ATA device. This data is stored in a global HDDATA structure for the drive. This function should be called once prior to calling any of the functions that get information from the drive information structure.

Parameters

None.

Return Value

Returns ATA_OK if the drive information is read successfully.
Returns RDY_TIMEOUT if the drive is not ready and a timeout occurs.
Returns BSY_TIMEOUT if the drive is busy and a timeout occurs.

Code Example

/* get the drive information from the ATA device */
if(ReadDriveID( ) == ATA_OK)
{
    return(TRUE);
}
else
{
    return(FALSE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


ATA Config Data

ATA Configuration Data

The following data related to the ATA Driver is user configurable and is contained in the config.c file at game level.

Initialisation Time Out

The initialisation timeout value for an ATA device is defined in the ATACFG structure:

/* ATA Compact Flash or Hard Drive */
const ATACFG ATACfg=
{
    1500, 	/* Initialisation time out */
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


ATA Defined Values

The following return values defined in the ATASTS enumeration are used by the ATA Driver:

Label | Meaning
ATA_OK | Signifies that the operation was successful
RDY_TIMEOUT | Signifies that a timeout occurred because the ATA device was not ready.
DRQ_TIMEOUT | Signifies that a timeout occurred when requesting data from the ATA device.
BSY_TIMEOUT | Signifies that a timeout occurred because the ATA device was busy.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Device Manager

The device manager module offers a number of functions for manipulating device drivers. This module also deals with system shutdown in the event of errors. Most of the functions in this module are for system use and will be of no interest to the game programmer.

API Functions

The following API functions are associated with this module:

Function | Description
InstallDevices | Installs the device drivers in the given list.

See Also

  • Defining a Device List
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Install Device Drivers API Function

Device Manager

API Function

BYTE InstallDevices( const INSTALLDEVICE* dlist )

Description

Install the device drivers in the given list.

Parameters

Parameter | Description
dlist | The list of device drivers to install.

Return Value

Return TRUE on success.
Return FALSE if one or more drivers have reported errors.

Code Example

/* install devices listed in DeviceLst */
if(InstallDevices(DeviceLst))
{
      return(TRUE);
}
else
{
      return(FALSE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Defining a Device List

A device list defines all of the device drivers to be installed for a given game application. Each entry in the device list is of type INSTALLDEVICE and consists of the following 4 elements:

Element | Description
Device | The address of the device driver structure to be installed.
Device Select Function | A pointer to the device select function. This function returns TRUE if the device is to be installed. If this field is zero the device is installed.
Configuration Select Function | A pointer to the configuration select function. The device driver structure contains a pointer to an array of configuration structures for the device. This function is responsible for calculating the index into this array and thereby selecting the configuration data to be used. If this field is zero configuration index zero is used.
Optional Parameter | This is an optional parameter, which is passed into the configuration select function. It will typically be some parameter that the configuration select function uses to determine which index to return. (For example a list of DIL switches).

Code Example

/* a simple device list to install all four Pluto 6 serial devices */
const	INSTALLDEVICE DeviceList[]=
{
    {&DUART0Device  ,0,0,0},
    {&SerialDevice  ,0,0,0},
    {&FPUART0Device ,0,0,0},
    {&FPUART1Device ,0,0,0},
    {0,0,0}
};

The device list for a gaming application is created in the file devices.c in the Application Module.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Entry Module

The entry module provides start-up code to perform low-level initialisation of the Pluto 6 hardware.
The entry module sets up the following on the ColdFire® processor:

Instruction caching | Cache processor instructions to optimise performance.
Chip select registers | Configure chip select registers for external devices.
Memory control registers | Configure external memory control.
Interrupt control registers | Configure ColdFire interrupt registers.
Interrupt mask registers | Configure ColdFire interrupt mask value.

Following processor configuration, system RAM is cleared and the code jump to the function main() to begin executing the game code.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Interrupt Module

Functionality is provided in the interrupt module to allow the user to install functions that will be run based on system interrupts.

API Functions

The following API functions is associated with this module:

Function | Description
InstallIntFnc | Installs a function into the given interrupt list.

See Also

  • Pluto 6 Interrupts
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Interrupt Module

API Function

BYTE InstallIntFnc(void(*fnc)(),void(**fnc_lst)())

Description

Add a pointer to an interrupt handler function fnc, to the end of the specified interrupt scheduler list fnc_lst.

Remarks

Before using this function refer to the Pluto 6 Interrupts page.

Parameters

Parameter | Description
fnc | Address of the function to be installed to the given interrupt list.
fnc_lst | Address of the interrupt list where the function fnc is to be installed.

Return Value

Returns TRUE on success.
If the interrupt scheduler list is full, FALSE is returned.
It is recommended that the return value is always tested.

Code Example

Let's consider that testinp() needs to be executed every 10ms:

static void testinp()
{
do something….
}

Thus testinp() will have to be installed into the list run every 10 ms. To do so InstallIntFnc needs to be called during initialisation, as follows:

if (InstallIntFnc( testinp, Int10msLst ) == FALSE)
{
/* testinp() will now be run every 10 ms */

error();
/* error: list is full */
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Interrupts

Seven interrupt scheduler lists are defined in the Pluto 6 software which are declared and initialised in config.c in the project directory:

void (*Int1msLst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*Int10msLst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*Int250msLst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntDuartLst[])()={0,0,0,0,EOF_FUNCTIONS};

void (*IntVideoLst[])()={0,0,0,0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntFpuartLst[])()={0,0,0,0,0,0,EOF_FUNCTIONS};
void (*IntDMALst[])()={0,0,0,0,EOF_FUNCTIONS};

Pluto 6 integrates several levels of interrupts. These levels of interrupt are fixed and should not be changed by the user. In certain case users may need to install their own driver or interrupt driven functions, which can be achieved by adding functions to the appropriate interrupt scheduler list.

Note: Caution must be exercised when making any changes to the interrupts. Modification of priorities or overloading of an interrupt list may stop the platform from working correctly. Modifying interrupt level will not necessarily improve the operation of a game. If you feel you need to modify the priority of interrupts please contact technical support for advice on alternative solutions.

Each interrupt scheduler list must be large enough to accommodate:

  • All of the interrupt handlers installed by the device drivers specified.
  • Any additional interrupt handlers installed by the user application.

InstallIntFnc() adds a pointer to an interrupt handler function fnc, to the end of the specified interrupt scheduler list fnc_lst.

The zeroed entries in each of the above lists are place holders for pointers to interrupt service routines. The number of entries in a list must be greater than or equal to the number of interrupts plus 2. The last entry must be EOF_FUNCTIONS.

The order of execution for handler functions is the same as the order of installation.

Installing User Defined Interrupt Functions

It is recommended that user defined interrupt functions are only installed in the following interrupt lists:

  • Int10msLst 10ms periodic interrupt list.
  • Int250msLst 250ms periodic interrupt list.

Note: Adding user defined interrupt functions to other interrupt lists (for example the video interrupt list) may result in undetermined behaviour in drivers that use the given interrupt.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Standard Peripherals Module

This module contains drivers that allow the game developer to control devices that are peripheral to the Pluto 6 control board but are commonly used in game development.

Standard Peripherals Module Components

Component | Description
Timer Driver | The timers module provides an API to use the Pluto 6 on board timers.
Generic Touch Screen Driver | The Generic touch screen driver provides a common API to specific touch screen controllers.
ELO Touch Screen Controller Driver | The ELO touch screen driver provides an API to allow developers to write applications using ELO touch screens. The basic functionality is accessed through the generic touch screen API. Advanced control functions are also provided that can be accessed directly.
Microtouch Touch Screen Controller Driver | The Microtouch touch screen driver provides an API to allow developers to write applications using Microtouch touch screens. The basic functionality is accessed through the generic touch screen API. Advanced control functions are also provided that can be accessed directly.
Generic Stepper Motor Driver | The Generic Stepper Motor driver provides a common API to control specific stepper motors.
Reel Stepper Motor Driver | The Reel Stepper Motor driver is a specialised driver that allows the developer to control reels in gaming applications. The functionality is accessed through the generic stepper motor API.
E2ROM Driver | The E2ROM driver module provides functions to read from and write data to the EEPROM device.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Timer Driver

The timer module is a device driver for controlling the system timers.

API Functions

The following API functions are associated with this module:

Function | Description
SetTimer | Loads a timer with a given time.
SetFreezeTimer | Loads a freeze timer with a given time.
WaitTime | Waits for the specified time before returning.
WaitFTime | Waits for the specified time before returning.

See Also

  • Timer Configuration Data
  • Timer Defined Types
  • Killing Timers
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Timer API Function

Timer Driver

API Function

BYTE SetTimer(TIMER *timerptr ,TIME time)

Description

The timer whose address is held in 'timerptr' is loaded with the given time. The timer is then installed into the timer list and will decrement every 10ms until the timer value reaches zero. The timer will then be removed from the timer list and will not be decremented further. If the timer is already active when 'SetTimer' is called it will not be loaded into the timer list for a second time but will be loaded with the new value and it will be decremented from there.

Timers set with 'SetTimer' continue to run when the system is shut down in the event of an error.

Parameters

Parameter | Description
timerptr | Address of the timer.
time | Value to load the timer with. The time value is in 10ms units.

Return Value

Return TRUE if the timer is successfully set.
Returns FALSE if there is no space on the timer list.

Code Example

/* Declare a timer */
TIMER timer1;

/* Load the declared timer to run for 1 second *
if(SetTimer(&timer1, 100))
{
    /*
    Space is available on the timer list so wait for the timer to expire
     */
    while(timer1)
    {

    };
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Freeze Timer API Function

Timer Driver

API Function

BYTE SetFreezeTimer(TIMER *freezetimerptr ,TIME time)

Description

The timer whose address is held in 'freezetimerptr' is loaded with the given time. The freeze timer is then installed into the freeze timer list and will decrement every 10ms until the timer value reaches zero. The timer will then be removed from the freeze timer list and will not be decremented further. If the timer is already active when 'SetFreezeTimer' is called it will not be loaded into the freeze timer list for a second time but will be loaded with the new value and it will be decremented from there.

Timers set with 'SetFreezeTimer' stop decrementing when the system is shut down in the event of an error and restart when the system comes out of shutdown.

Parameters

Parameter | Description
freezetimerptr | Address of the freeze timer.
time | Value to load the freeze timer with. The time value is in 10ms units.

Return Value

Return TRUE if the freeze timer is successfully set.
Return FALSE if there is no space on the freeze timer list.

Code Example

/* Declare a timer */
TIMER freezetimer1;

/* Load the declared freeze timer to run for 2 seconds *
if(SetFreezeTimer(&freezetimer1, 200))
{
    /*
    Space is available on the freeze timer list so wait for the timer to expire
    */
    while(freezetimer1)
    {

    };
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Wait Time API Function

Timer Driver

API Function

BYTE Wait(TIME time)

Description

Wait for the specified time before returning. This function uses SetTimer so the time continues to count down during shutdown.

Parameters

Parameter | Description
time | Value to load the timer with. The time value is in 10ms units.

Return Value

Returns TRUE if the operation is successful.
Returns FALSE if there is no space on the timer list.

Code Example

/* Wait for 1 second *
Wait(100);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Wait Freeze API Function

Timer Driver

API Function

BYTE WaitF(TIME time)

Description

Wait for the specified time before returning. This function uses SetFreezeTimer so the time stops counting down during shutdown.

Parameters

Parameter | Description
time | Value to load the freeze timer with. The time value is in 10ms units.

Return Value

Returns TRUE if the operation is successful.
Returns FALSE if there is no space on the timer list.

Code Example

/* Wait for 2 seconds using a freeze timer *
WaitF(100);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Timer Configuration Data

The following data related to the Timer Device Driver is user configurable and is contained in the config.c file at game level.

Declaring a List of Timers

A list of available timers is specified in the game configuration data. When a timer is set it is added to the list. When all available spaces in the list are occupied no further timers can be set until a running time has expired and is therefore removed from the list. This applies to both normal and freeze timers.

/* declare a list to hold up to 8 timers */
TIMER* TimerLst[8];
const	WORD	NofTimers=(sizeof(TimerLst)/sizeof(TimerLst[0]));
/* declare a list to hold up to 8 freeze timers */
TIMER* FTimerLst[8];
const	WORD	NofFTimers=(sizeof(FTimerLst)/sizeof(FTimerLst[0]));
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Timer Defined Values

Timer Defined Types

The following types are defined for use with the timer device driver:

Defined Type | Description
TIMER | This a volatile 16 bit value holding the current timer value.
TIME | This is a 16 bit time value.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Killing Timers

The following points should be condsidered when using timers:

Creating Local Timers in Functions

In the following example a local timer is created in a function. The timer runs until it has expired unless an input is triggered which will result in the function returning.

void func1(void)
{
    /* create a timer */
    TIMER timer1;

    /* set the timer to time out after 10 seconds */
    SetTimer(&timer1 , 1000);

    /* loop until the timer = 0 */
    while(timer1)
    {
        /* test an input to see whether to exit before the timer has expired */
        if(Test(IP16))
               break;
    }
}

By creating the timer in a function in this way it will be created on the stack. The address of the timer has been added to the timer list, and will be retained until the timer expires. By exiting from the function before the timer has expired the address that was passed to the timer list is no longer valid. This will result in undefined behaviour, in the worst case system crash.

To avoid this the function aabove should be re-writted as follows:

void func1(void)
{
    /* create a timer */
    TIMER timer1;

    /* set the timer to time out after 10 seconds */
    SetTimer(&timer1 , 1000);

    /* loop until the timer = 0 */
    while(timer1)
    {
        /* test an input to see whether to exit before the timer has expired */
        if(Test(IP16))
        {
            /*
               set the timer to 0. This will force the timer to expire and
               it will be removed from the timer list before returning from
               the function
            */
            SetTimer(&timer1 , 0);
            break;
        }
    }
}

General Principal

As a general principal all timers that are created should either be allowed to run to completion (timer = 0), or be forced to expire using the SetTimer(&timer1 , 0) so that they are removed from the timer list.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stepper Motor Driver

This module contains generic wrapper functions which call the appropriate functions from the given stepper driver.

API Functions

The following API functions are associated with this module:

Function | Description
GetNofMotors | Gets the number of stepper motors controlled by the given stepper motor device driver.
InitialiseStepMotors | Initialises all the stepper motors controlled by the given device driver.
StepMotorsIdle | Tests the status of all motors controlled by the device.
DetectStepMotorOptos | Returns a 32 bit integer with each bit representing the status of each motor.
SpinStepMotorsToTab | Spins all motors controlled by the device to their reference positions.
SpinStepMotor | The motor is set up to spin the given distance.
StopStepMotor | Brings the motor to rest on the first possible motor position.
GetStepMotorPosn | Returns the current motor position.
StepMotorSpinning | Tests the status of the motor.
GetStepMotorTabsMissed | Gets the number of times the motor has passed through the reference position.
GetStepMotorPosnCorrected | Gets the number of times the motors internal position variable has been corrected.
ClearStepMotorErrors | Clears the internal position detection variables.

See Also

  • Stepper Configuration Data
  • Stepping Motor Profiles
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get No of Motors API Function

Stepper Motor Driver

API Function

WORD GetNofMotors(const DEVICE* dev)

Description

Get the number of stepper motors controlled by the given stepper motor device driver.

Parameters

Parameter | Description
dev | Address of the stepper device.

Return Value

Returns the number of stepping motors controlled by the given device.

Code Example

/* variable to contain number of motors */
WORD numberofmotors;

/* get number of motors controlle by the stepper device */
numberofmotors = GetNofMotors(&StepperDevice);

InitialiseStepMotors(&StepperDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Initialise Step Motors API Function

Stepper Motor Driver

API Function

void InitialiseStepMotors(const DEVICE* dev)

Description

Initialise all the stepper motors controlled by the given device driver. Spin all motors to the reference position and detect missing or faulty motors/position sensors. If errors are detected the system shuts down and calls the error handler.

Parameters

Parameter | Description
dev | Address of the stepper device.

Return Value

None.

Code Example

/* initialise the stepper motors controlled by the stepper device */
InitialiseStepMotors(&StepperDevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Step Motors Idle API Function

Stepper Motor Driver

API Function

BYTE StepMotorsIdle(const DEVICE* dev);

Description

Test the status of all motors controlled by the device and return TRUE if they are all idle.

Parameters

Parameter | Description
dev | Address of the stepper device.

Return Value

Return TRUE if all motors are idle.
Return FALSE if any motor is spinning.

Code Example

/*  Wait for all motors to finish */
while(!StepMotorsIdle(&StepperDevice));
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Detect Step Motor Optos API Function

Stepper Motor Driver

API Function

LONG DetectStepMotorOptos(const DEVICE* dev)

Description

Read the status of the optical position sensor of each motor.

Parameters

Parameter | Description
dev | Address of the stepper device.

Return Value

Return a 32 bit integer with each bit representing the status of each motor. A 1 means the motor is at its reference position (the sensor is read as active).The least significant bit represents the first motor (motor index = 0). Unused bits are set to zero.

Code Example

/* variable to contain number of motors */
WORD numberofmotors;

/* get the number of motors that the driver is controlling */
numberofmotors = GetNofMotors(&StepperDevice);

/* read the optical position sensor for each motor */
if(DetectStepMotorOptos(&StepperDevice) == (1<<n)-1)
{
    /* All motors are at reference position */
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Spin Step Motors to Tab API Function

Stepper Motor Driver

API Function

void SpinStepMotorsToTab(const DEVICE* dev, WORD rampidx)

Description

Spin all motors controlled by the device to their reference positions.

Parameters

Parameter | Description
dev | Address of the stepper device.
rampidx | The index to the ramp table to use. The ramp table specifies how the motor is controlled and the delays between each step. This information is found in the reel type structure.

Return Value

None.

Remarks

Refer to Stepping Motor Profiles for a description of the reel type structure.

Code Example

/* variable to contain number of motors */
WORD numberofmotors;

/* spin the motors to their reference positions */
SpinStepMotorsToTab(&StepperDevice);

/* get the number of motors that the driver is controlling */
numberofmotors = GetNofMotors(&StepperDevice);

/* read the optical position sensor for each motor */
if(DetectStepMotorOptos(&StepperDevice) == (1<<n)-1)
{
    /* All motors are at reference position */
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Spin Step Motor API Function

Stepper Motor Driver

API Function

void SpinStepMotor(const DEVICE* dev, WORD motidx, WORD dist, WORD rampidx)

Description

The motor is set up to spin the given distance. Control returns from the function immediately and the reel spins and stops in its own time. If the motor is not in the idle state when this function is called it first waits for the motor to enter the idle state and then starts the next spin and returns.

Parameters

Parameter | Description
dev | Address of the stepper device.
motidx | Specifies the motor to spin. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.
dist | The distance to spin the motor. The distance is in motor positions not physical motor steps. The relationship between motor position and physical motor steps is contained in the motor type structure. Negative value will cause the motor to spin in reverse.
rampidx | The index to the ramp table to use. The ramp table specifies how the motor is controlled and the delays between each step. This information is found in the reel type structure.

Return Value

None.

Remarks

Refer to stepping motor profiles for a description of the reel type structure.

Code Example

/*
Spin motor 0 of 'StepperDevice' 12 motor positions using the 96RPM control ramp
*/
SpinStepMotor(&StepperDevice,0,12,RAMP_96);

while(!StepMotorsIdle)
{
    /* Wait for all motors to finish */
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stop Step Motor API Function

Stepper Driver

API Function

void StopStepMotor(const DEVICE* dev,WORD motidx)

Description

Bring the motor to rest on the first possible motor position.

Parameters

Parameter | Description
dev | Address of the stepper device
motidx | Specifies the motor to stop. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.

Return Value

None.

Remarks

For this function to work the motor must be spinning with one of the 'skill' control ramps. The spin must be given a non-zero distance which translates to more physical steps than the 'ramp up' phase of the control ramp. Having reached full speed the motor will spin until it is stopped using this function.

Code Example

/*
Start the motor spinning */
*/
SpinStepMotor(&StepperDevice,0,12, RAMP_SKILLMED);

while(!MotorsIdle(&StepperDevice))
{
    /* stop the motor when input IP20 becomes active */
    if(Test(IP20))
    {
        StopMotor(StepperDevice,0);
    }
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Step Motor Posn API Function

Stepper Motor Driver

API Function

WORD GetStepMotorPosn(const DEVICE* dev, WORD motidx)

Description

Return the current motor position. The relationship between motor position and physical motor steps is contained in the motor type structure.

Parameters

Parameter | Description
dev | Address of the stepper device.
motidx | Specifies which motor to get the position of. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.

Return Value

The current motor position in the range 0 to N-1 (where N is the number of motor position in a complete revolution).

Code Example

/* variable to contain motor position */
WORD position;

/* get the position of motor 0 */
position = GetStepMotorPosn(&StepperDevice,0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Step Motor Spinning API Function

Stepper Motor Driver

API Function

BYTE StepMotorSpinning(const DEVICE* dev, WORD motidx)

Description

Test the status of the motor and return TRUE if the motor is spinning. The motor will leave the spinning state some time before entering the idle state. This function should be used to synchronise events with the motor stopping.

Parameters

Parameter | Description
dev | Address of the stepper device.
motidx | Specifies the motor to test. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.

Return Value

Return TRUE if the motor is spinning.
Return FALSE if the motor is not spinning.

Code Example

/* wait for motor 0 to stop spinning */
while(StepMotorSpinning(&StepperDevice,0));
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Step Motor Tabs Missed API Function

Stepper Motor Driver

API Function

WORD GetStepMotorTabsMissed(const DEVICE* dev, WORD motidx)

Description

Get the number of times the motor has passed through the reference position without the position sensor being read as active. The count is kept internally and cleared by ClearStepMotorErrors().

Parameters

Parameter | Description
dev | Address of the stepper device.
motidx | Specifies the motor to test. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.

Return Value

Return the number of times the position sensor has been expected but not detected.

Code Example

/* variable to error reading */
WORD error;

/*  get the number of tabs missed for motor 0 */
error = GetStepMotorTabsMissed(&StepperDevice,0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Step Motor Posn Corrected API Function

Stepper Motor Driver

API Function

WORD GetStepMotorPosnCorrected(const DEVICE* dev, WORD motidx)

Description

Get the number of times the motors internal position variable has been corrected as a result of the position sensor being read as active when the position variable has not shown the reference position. The count is kept internally and cleared by ClearStepMotorErrors().

Parameters

Parameter | Description
dev | Address of the stepper device.
motidx | Specifies the motor to test. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.

Return Value

Return the number of times that motor position has been corrected.

Code Example

/* variable to error reading */
WORD error;

/*
 get the number of times the position has been corrected for motor 0
 */
error = GetStepMotorPosnCorrected(&StepperDevice,0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Step Motor Errors API Function

Stepper Motor Driver

API Function

void ClearStepMotorErrors(const DEVICE* dev, WORD motidx)

Description

Clear the internal position detection variables.

Parameters

Parameter | Description
dev | Address of the stepper device.
motidx | Specifies the motor whose errors are to be cleared. This is the index to the motor in the device motor list, which is found in the device configuration structure in config.c.

Return Value

None.

Code Example

/* clear the errors for motor 0 */
ClearStepMotorErrors(&StepperDevice,0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stepper Config Data

Stepper Configuration Data

The following data related to the Stepper Device Driver is user configurable and is contained in the config.c file at game level.

For each reel that the game application uses the following data must be set:

/* Reel 1 */
/* clear stepper variables */

STEPPERVARS reel1_ram =
{
    0,0,		/* Set position/index */
    0,		/* Direction */
    0,0,		/* Pattern table/index */
    0,		/* Vector table */
    0,0,0,		/* Delay table index timer */
    0,0,		/* Pix mask/opto count */
    0,0,		/* Spin/enable flags */
    0,0		/* Pos correction/tab missed */
};

STEPPERZVARS reel1_ram2;

/* set the inputs and outputs */
const REEL_ADDR reel1_addr =
{
    REEL1_OPS,
    REEL1_IP
};

/* configure the reel – in this case using the RM161680 ramp tables */
const STEPPER reel1 =
{
    &reel1_addr,
    &RM161680,
    &reel1_ram,
    &reel1_ram2,
    0
};

Once all of the reels have been configured they must be a added to the stepper list. In the example code below four reel steppers were previously defined and are used to create the stepper list.

/* create a list of all of the stepper devices */
const	STEPPER* const	stepperlist[]=
{
    &reel1,
    &reel2,
    &reel3,
    &reel4,
    EOF_STEPPERS
};

Each member of the stepper list is then configured:

/* configure the steppers in the list */
const	STEPCFG StepperCfg=
{
    stepperlist,
    5,	/* No. of steps to wake up steppers */
    50,	/* delay between steps */
    50	/* opto delay */
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stepping Motor Profiles

Overview

The generic stepper motor driver will typically be used to control reels and can handle many different types of reel. There is no limit in the software to the number of reels or the number of different types of reel that can be controlled simultaneously.

All the information defining a particular reel type is contained in a REEL_TYPE structure. An example of a reel structure is in the Custom Peripheral driver library and it is suggested that any new reel types defined be added to this library. (libcustomperipherals.a)

Defining a New Reel Type

The type declaration for the REEL_TYPE structure in stepper.h should be used when defining a new type structure.

typedef	struct reel_type
{
    WORD		steps_per_rev;
    WORD		steps_per_symbol;
    BYTE		min_opto;
    BYTE		tolerance;
    BYTE		revpos;
    const RAMP	*ramps[MAX_RAMPS];
} REEL_TYPE;

steps_per_rev
The number of stepper motor steps required to move the reel one complete revolution.

steps_per_symbol
The number of stepper motor steps required to move the reel one whole reel symbol.

min_opto
The number of times the position sensor must be seen during one step to activate the position correction software.

tolerance
This is the size of the position error in motor steps, which is allowable without activating the position correction software.

revpos
This should be set TRUE if the position detection software is to be active whilst the reel is spinning backwards. This position correction software is always active whilst the reel is spinning forwards.

ramps
This is a list of pointers to RAMP structures. A RAMP structure contains all the information required to define a particular type of reel movement. There are two ramps for system use, 'system' and 'initialisation' ramps, In addition there are ramps for spinning at 69RPM, 78RPM, 89RPM, 96RPM, and 104RPM.There is provision for three different nudge ramps and three different 'skill stop' ramps.

The RAMP Structure

The RAMP structure allows the stepper driver to be very flexible in the way it can control the reels. A RAMP structure can be defined to make a reel do almost anything.

typedef	struct ramp
{
    const WORD	*pattern_tbl;
    WORD		pixmask;
    void		(*const *vector_tbl)(const void*);
    const WORD	*delay_lst;
} RAMP;

pattern_tbl
The pattern table defines the energising sequence of the four phases of the stepper motor. To move one step the reel increments its index into this table and writes the new pattern out to the motor coils.

pixmask
Each time the pattern table index is incremented (or decremented for reverse spin) it is logically ANDed with this value to wrap it around at the end of the table.

vector_tbl
This is a list of function pointers to the functions, which will be called by the stepper driver in order to control the reel. The standard vector tables provided will suffice for most situations but for any special requirements a new vector table may be defined and new functions written.

delay_lst
A list of delays (in milliseconds) required to time the various steps. The vector functions will access these delays and the meaning of any particular delay is dependant on the vector functions used and the number of steps controlled by each vector function. For the standard vector functions (RampUp, Run, and RampDown) the first number indicates the number of steps to be controlled by that vector function and that is followed by the a delay for each step. It is left to the vector functions to manipulate the index into this delay list.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Driver

Generic Touchscreen Driver

The Generic Touchscreen module provides a common API allowing game developers to write touchscreen applications that are independent of the underlying hardware controller. Using the generic driver applications can be successfully created that will run with either of the supported touchscreen controllers using single set of functions.

The standard peripherals library provides support for the following touchscreen hardware controllers:

  • ELO
  • Microtouch

A touchscreen driver requires the services of a serial port on the Pluto 6 control board. Any of the available serial ports can be allocated to work with the touchscreen controller.

Note: If CTS/RTS are wired to the ELO touchscreen and the Serial Device does not handle these signals, the ELO touchscreen will NOT work. Heber advises to use RX/TX/Ground only for this device.

Touchscreen Driver Structure

API Functions

The following API functions are associated with this module:

Function | Description
TouchScreenSetScale | Sets the screen resolution for the Touchscreen Controller.
TouchScreenCalibrate | Calibrates the Touchscreen controller.
TouchScreenInit | Initialise the Touchscreen Controller
TouchScreenReset | Resets the Touchscreen Controller.
TouchScreenIdentify | Identifies the Touchscreen Controller.
TouchScreenSetSerial | Sets the Touchscreen serial communication parameters.
TouchScreenSetMode | Sets the reporting mode for the Touchscreen controller.
TouchScreenSetScale | Set the screen resolution for the Touchscreen Controller.
TouchScreenCommsMode | Set the communication mode with the Touchscreen Controller.
TouchScreenGetNextData | Get the next Touch Data Packet from the Touch Event Buffer.
TouchScreenGetX | Returns the scaled and calibrated screen touch X position from a Touch Data Packet.
TouchScreenGetY | Returns the scaled and calibrated screen touch Y position from a Touch Data Packet.
TouchScreenGetZ | Returns the screen touch Z value (touch pressure) from a Touch Data Packet.
TouchScreenGetTouchStatus | Returns the screen touch status from a Touch Data Packet.

See Also

  • Touchscreen Controller Installation and Configuration
  • Supported Touchscreen Controller Serial Interfaces
  • Touchscreen Controller Calibration
  • Touchscreen Controller Modes of Operation
  • Touchscreen Defined Values
  • Touchscreen Defined Data Types
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Scale API Function

Generic Touchscreen Driver

API Function

void TouchScreenSetScale(WORD xmax, WORD ymax, BYTE xinvert, BYTE yinvert)

Description

Set the screen resolution for the Touchscreen Controller.

Parameters

Parameter | Description
xmax | Touchscreen X Resolution (0 < xmax < = 1024).
ymax | Touchscreen Y Resolution (0 < ymax < = 1024).
xinvert | 0 (Screen Left = 0, Screen Right = xmax). 1 (Screen Left = xmax, Screen Right = 0).
yinvert | 0 (Screen Left = 0, Screen Right = ymax). 1 (Screen Left = ymax, Screen Right = 0)

Return Value

None.

Code Example

#define NORMAL 0
#define INVERTED 1
/*
bottom left x,y co-ordinates = 0,0
top right x,y co-ordinates = 799,599
 */
UWORD x_resolution = 800;
UWORD y_resolution = 600;

BYTE x_invert = NORMAL;
BYTE y_invert = INVERTED;

TouchScreenSetScale(x_resolution, y_resolution, x_invert, y_invert);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Callibrate API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenCalibrate(const DEVICE* dev, UWORD step_number)

Description

Calibrate the Touchscreen Controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device.
step_number | Step number in the three step controller calibration. Use values from 1-3 incrementing on successive calls to this function (multi-step calibration).

Return Value

Return 0 if the calibration step is successful OK.
Return a non-zero comms error code if the calibration fails. Error code values are listed in the Touchscreen Defined Values page under API Function Return Codes.

Remarks

For further information on calibration refer to the Touchscreen Controller Calibration page.

Code Example

The following code example contains an example function that can be used to calibrate a touchscreen controller. The function does the following:

  • Displays an image on the bottom left of the screen. When the image is pressed on the touchscreen x axis minimum and y axis maximum values are set.
  • Displays an image on the top right of the screen. When the image is pressed on the touchscreen x axis maximum and y axis minimum values are set.

The set values are then stored in the global TOUCHCALIBDATA structure held in non-volatile system memory.

/* variables to hold video memory addresses */
LONG screen0;
LONG sprite1;

/*
The target sprite is a small bitmapped image of a touch target, for
example crosshairs
*/
extern const WORD target[];
extern const WORD target_width;
extern const WORD target_height;

/*
3 step calibration function taking the device address of the touchscreen
controller as a parameter
*/
WORD demo_calibrate(const DEVICE* dev)
{
    WORD x;
    WORD y;

    /* Base layer - screen 0 */
    InitDrawframe(0, screen0, HSIZE);

    /*
    STEP 1: Initial Calibration
    */

    if(TouchScreenCalibrate(dev, 1))
    {
        return(1);
    }

    /*
    STEP 2: Touch Calibration Mark at bottom left of screen
    */

    x = (800/8);
    y = VSIZE-(VSIZE/8);

    ClearLayer(&Calypso32Layer[BL_LAYER],
    0, HSIZE, 2);
    PutSprite(screen0, x - target_width/2, y - target_height/2,
    HSIZE, sprite1, target_width, target_height, 0, 2);

    if (TouchScreenCalibrate(dev, 2))
    {
        return(1);
    }

    /*
    STEP 3: Touch Calibration Mark at top right of screen
    */

    x = 800-(800/8);
    y = (VSIZE/8);

    ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, 2);
    PutSprite(screen0, x - target_width/2, y - target_height/2,
    HSIZE, sprite1, target_width, target_height, 0, 2);

    if (TouchScreenCalibrate(dev, 3))
    {
        ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, 2);
        return(1);
    }

    ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, 2);

    return(0);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Init API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenInit(const DEVICE* dev)

Description

Initialise the Touchscreen Controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device.

Return Value

Unused.

Remarks

For further information on initialisation refer to the Touchscreen Controller Installation and Configuration page.

Code Example

/* declare a device pointer */
const DEVICE* touch_screen_device;

/*
set the device pointer to the address of the touchscreen controller,
in this example the MicroTouch controller
*/
touch_screen_device = &MicroTouchDevice;

/* initialise the MicroTouch touchscreen device */
TouchScreenInit(touch_screen_device);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Reset API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenReset(const DEVICE* dev, UBYTE reset_type)

Description

Reset the Touchscreen Controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device.
reset_type | Type of reset (see Touchscreen Defined Values page).

Return Value

Not used.

Code Example

/* declare a device pointer */
const DEVICE* touch_screen_device;

/*
set the device pointer to the address of the touchscreen controller,
in this example the ELO controller
*/
touch_screen_device = &ELODevice;

/* hard reset the ELO touchscreen device */
TouchScreenReset(touch_screen_device, HARD_RESET);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Identify API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenIdentify(const DEVICE* dev, TOUCHIDENTITY *touchidentity)

Description

Identify the Touchscreen Controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device.
touchidentity | Address of a touch TOUCHINDENTITY structure to hold information about the touchscreen controller. (See Touchscreen Defined Data Types page).

Return Value

Return 0 if the operation step is successful OK.
Return a non-zero comms error code if the operation fails. Error code values are listed in the Touchscreen Defined Values page under API Function Return Codes.

Code Example

This example gets the identity information from a MicroTouch touchscreen controller and outputs the data to a serial port.

/* declare a touch identity structure */
TOUCHIDENTITY touchidentity;

/*
declare a BYTE array to hold the controller information fields to be output
*/
BYTE output_string[64];

/* declare a device pointer */
const DEVICE* touch_screen_device;

/*
set the device pointer to the address of the touchscreen controller,
in this example the MicroTouch controller

*/
touch_screen_device = &MicroTouchDevice;

/* get the identity information from the MicroTouch controller */
if(TouchScreenIdentify(touch_screen_device, &touchidentity) == 0)
{
    /* output the identity data to the serial port */
    sprintf(output_string, "%s\r\n", touchidentity.model);
    TxString(&SerialDevice,1, output_string);
    sprintf(output_string, "%s\r\n", touchidentity.revision);
    TxString(&SerialDevice,1, output_string);
    sprintfoutput_string, "%s\r\n", touchidentity.features);
    TxString(&SerialDevice,1, output_string);
    sprintf(output_string, "%s\r\n", touchidentity.status);
    TxString(&SerialDevice,1, output_string);
}
else
{
    TxString(&SerialDevice,1, "Touch screen comms error\r\n");
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Serial API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenSetSerial(const DEVICE* dev, BYTE baud, BYTE bits, BYTE stop, BYTE parity, BYTE handshake)

Description

Set the touchscreen serial communication parameters.

By default the touchscreen controller serial port has the following configuration:

  • 9600 baud
  • 8 data bits
  • 1 stop bit
  • no parity
  • no handshake

The default settings are common for both the ELO and MicroTouch touchscreen controllers and are applied during driver initialisation. It is recommended that the defaults settings are used.

Parameters

Parameter | Description
dev | Address of the touchscreen device.
baud | Baud rate setting.
bits | Number of data bits.
stop | Number of stop bits.
parity | Parity setting.
handshake | Handshaking setting.

Return Value

Return 0 if the operation step is successful OK.
Return a non-zero comms error code if the operation fails. Error code values are listed in the Touchscreen Defined Values page under API Function Return Codes.

Remarks

For further information touchscreen serial ports refer to the Touchscreen Controller Installation and Configuration page. Pre-defined values for serial parameter settings are listed on the Touchscreen Defined Values page.

Code Example

This example sets the serial communications parameters in the MicroTouch controller to the following:

  • 1200 Baud
  • 8 data bits
  • 2 stop bits
  • even parity
  • no handshaking
/* declare a device pointer */
const DEVICE* touch_screen_device;

/*
set the device pointer to the address of the touchscreen controller,
in this example the MicroTouch controller
*/
touch_screen_device = &MicroTouchDevice;

/* Configure the MicroTouch serial port parameters */
if(TouchScreenSetSerial(touch_screen_device, BAUD1200, BITS8,
                 STOP2, PARITYEVEN, 0) != 0)
{
    TxString(&SerialDevice,1, "Serial configuration failed\r\n");
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Mode API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenSetMode(const DEVICE* dev, UBYTE mode)

Description

Set the reporting mode for the touchscreen controller.

Parameters

Parameter | Description
dev | Address of the touchscreen device.
mode | Reporting mode (see Reporting Mode Defined Values page). The value can be a single mode or combination of those available.

Return Value

Return 0 if the operation step is successful OK.
Return a non-zero comms error code if the operation fails. Error code values are listed in the Touchscreen Defined Values page under API function return codes.

Remarks

The mode value can be a single mode or combination of the reporting modes available. For a list pre-defined modes refer to the Touchscreen Defined Values page.

Code Example

This example sets the ELO controller to report the following events:

  • Down movement on the screen
  • Streaming (touching the screen but not moving)
  • Up movement on the screen
/* declare a device pointer */
const DEVICE* touch_screen_device;

/*
set the device pointer to the address of the touchscreen controller,
in this example the ELO controller
*/
touch_screen_device = &ELODevice;

/* set the reporting mode */
if(TouchScreenSetMode(touch_screen_device,DOWN_REPORT |
                STREAM_REPORT | UP_REPORT) != 0)
{
    TxString(&SerialDevice,1, "Report mode setting failed\r\n");
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Scale API Function

Generic Touchscreen Driver

API Function

void TouchScreenSetScale(WORD xmax, WORD ymax, BYTE xinvert, BYTE yinvert)

Description

Set the screen resolution for the Touchscreen Controller.

Parameters

Parameter | Description
xmax | Touchscreen X Resolution (0 < xmax <= 1024).
ymax | Touchscreen Y Resolution (0 < ymax <= 1024).
xinvert | 0 Screen Left=0, Screen Right= X max. 1 Screen Left=Xmax, Screen Right= 0.
yinvert | 0 Screen Left=0, Screen Right= Y max. 1 Screen Left=Ymax, Screen Right= 0.

Return Value

None.

Code Example

This example code scales the touchscreen that has dimensions of 1024x1024 to a physical monitor display size of 800x600. The x and y inversion parameters are set such that touch position is calculated from the top left of the screen.

/* co-ordinate inversion settings */
#define NORMAL 0
#define INVERTED 1

/* define the resolution x and y limits of the physical display */
#define XRES 800
#define YRES 600

/*
Scale the touch dimensions against the size of the physical display.
Set the xinvert position to left 0, right 800.
Set the yinvert position to left 600, right 0.
*/
TouchScreenSetScale(XRES, YRES, NORMAL, INVERTED);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Comms Mode API Function

Generic Touchscreen Driver

API Function

void TouchScreenCommsMode(const DEVICE *dev, BYTE mode)

Description

Set the communication mode with the Touchscreen Controller. In general this function is only used to set the controller to data streaming mode following initialisation. The mode setting sequence for general usage is demonstrated below:

  • Install driver - controller is set to COMMAND_MODE by installation function
  • Configure controller - controller remains in COMMAND_MODE
  • Use touchscreen in application - controller must be explicitly set to TOUCH_DATA_MODE

Parameters

Parameter | Description
dev | Address of the touchscreen device.
mode | Communications mode.

Return Value

None.

Remarks

For a list pre-defined modes refer to the Touchscreen Defined Values page.

Code Example

The following code example sets the MicroTouch touchscreen controller to TOUCH_DATA_MODE to allow touch data streaming for use in an application.

/* declare a device pointer */
const DEVICE* touch_screen_device;

/* declare a touch packet to hold touch data */
TOUCHDATA packet;

/* variables to hold data retrieved from packet */
UWORD x;
UWORD y;
UBYTE status;

/*
set the device pointer to the address of the touchscreen controller,
in this example the MicroTouch controller
*/
touch_screen_device = &MicroTouchDevice;

/*
touchscreen controller  has been installed and configured and is
still in COMMAND_MODE
*/

/* set controller to start streaming touch data */
TouchScreenCommsMode(touch_screen_device, TOUCH_DATA_MODE);

/* read the next data packet from the buffer */
if(TouchScreenGetNextData(&packet) == 0 )
{
    /* Touch Data available in buffer */
    /* read data from packet */
    x = TouchScreenGetX(&packet);
    y = TouchScreenGetY(&packet);
    status = TouchScreenGetTouchStatus(&packet);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Next Data API Function

Generic Touchscreen Driver

API Function

UBYTE TouchScreenGetNextData(TOUCHDATA *touch_packet)

Description

Get the next Touch Data Packet from the Touch Event Buffer.

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to store the data in (see Touchscreen Defined Data Types).

Return Value

Return 0 if the read was successful. Return 1 if there is no data in the buffer.

Remarks

For details of the touch packet data structure refer to the Touchscreen Defined Data Types page.

Code Example

The following code example uses the ELO touchscreen controller to read touch data from the data packet buffer.

/* declare a device pointer */
const DEVICE* touch_screen_device;

/* declare a touch packet to hold touch data */
TOUCHDATA packet;

/* variables to hold data retrieved from packet */
UWORD x;
UWORD y;
UBYTE status;

/*
set the device pointer to the address of the touchscreen controller, in this example the ELO controller
*/
touch_screen_device = &ELODevice;

/* set controller to start streaming touch data */
TouchScreenCommsMode(touch_screen_device, TOUCH_DATA_MODE);

/* read the next data packet from the buffer */
if(TouchScreenGetNextData(&packet) == 0 )
{
    /* Touch Data available in buffer */
    /* read data from packet */
    x = TouchScreenGetX(&packet);
    y = TouchScreenGetY(&packet);
    status = TouchScreenGetTouchStatus(&packet);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get X API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenGetX(TOUCHDATA *touch_packet)

Description

Returns the scaled and calibrated screen touch X position from a Touch Data Packet. The scaling applied must be initially specified using function TouchScreenSetScale().

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from.

Return Value

Returns the x value from the touch packet.

Remarks

For details of the touch packet data structure refer to the Touchscreen Defined Data Types page.

Code Example

UWORD x;
TOUCHPACKET packet;

/* get x data from the touch packet */
x = TouchScreenGetX(&packet);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Y API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenGetY(TOUCHDATA *touch_packet)

Description

Returns the scaled and calibrated screen touch Y position from a Touch Data Packet. The scaling applied must be initially specified using function TouchScreenSetScale().

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from.

Return Value

Returns the y value from the touch packet.

Remarks

For details of the touch packet data structure refer to the Touchscreen Defined Data Types page.

Code Example

UWORD y;
TOUCHPACKET packet;

/* get y data from the touch packet */
y = TouchScreenGetY(&packet);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Z API Function

Generic Touchscreen Driver

API Function

UWORD TouchScreenGetZ(TOUCHDATA *touch_packet)

Description

Returns the screen touch Z value (touch pressure) from a Touch Data Packet (If supported by the Touchscreen hardware).

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from.

Return Value

Returns the z value (0-255) from the touch packet. If pressure sensitivity is not supported by the hardware the return value is dependent on the packet data structure component initialisation value. If the packet data structure was not initialised the return value in indeterminable.

Remarks

For details of the touch packet data structure refer to the Touchscreen Defined Data Types page.

Code Example

UWORD z;
TOUCHPACKET packet;

/* get z data from the touch packet */
z = TouchScreenGetZ(&packet);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Touch Status API Function

Generic Touchscreen Driver

API Function

UBYTE TouchScreenGetTouchStatus(TOUCHDATA *touch_packet)

Description

Returns the screen touch status from a Touch Data Packet.

Parameters

Parameter | Description
touch_packet | Address of the touch data packet structure to read the data from.

Return Value

Returns the packet status information based on the touch event. The following bits represent the possible events if set:
Bit0 = 1 DOWN_EVENT Touch down
Bit1 = 1 STREAM_EVENT Continuous touch
Bit2 = 1 UP_EVENT Lift up

Remarks

For details of the touch packet data structure refer to the Touchscreen Defined Data Types page.

Code Example

UBYTE status;
TOUCHPACKET packet;

/* get z data from the touch packet */
status = TouchScreenGetStatus(&packet);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Controller Configuration

Touchscreen Controller Installation and Configuration

Installation

To use a specific Touchscreen Controller the device driver must be added to the DeviceList in the file devices.c in the project directory. The game applications should then reference the loaded device driver for touchscreen related operations.

To install the ELO device driver add the following to the DeviceList in the file devices.c:

const	INSTALLDEVICE	DeviceList[]=
{
    /*
    add this line to the device list to install the
    ELO touchscreen device driver
    */
    {&EloDevice ,0,0,0},
};

To install the MicroTouch device driver add the following to the DeviceList in the file devices.c:

const	INSTALLDEVICE	DeviceList[]=
{
    /*
    add this line to the device list to install the
    MicroTouch touchscreen device driver
    */
    {&MicroTouchDevice,0,0,0},
};

For further information on installing devices, refer to the Installing Device Drivers page.

Referencing the Loaded Device Driver

To use the loaded touchscreen device driver with the generic touchscreen API functions a reference to the driver must be used.

The following code examples demonstrate using the generic initialisation function TouchScreenInit() with references to the touchscreen controllers:

Using the ELO touchscreen controller:

/* declare a device */
const DEVICE* touchscreendev;
/*
set the device to the address of the ELO touchscreen device driver
*/
touchscreendev = &EloDevice;
/*
initialise the ELO touchscreen device using the
generic initialisation function
*/
TouchScreenInit(touchscreendev );

Using the MicroTouch Touchscreen Controller:

/* declare a device */
const DEVICE* touchscreendev;
/*
set the device to the address of the MicroTouch
touchscreen device driver
*/
touchscreendev = &MicroTouchDevice;
/*
initialise the MicroTouch touchscreen device using the
generic initialisation function
*/
TouchScreenInit(touchscreendev);

Configuring the Touchscreen Device Driver with a Serial Port

A touchscreen device requires a serial port to allow communication between the touchscreen controller and the Pluto 6 control board. Any of the available serial ports can be allocated to the touchscreen driver. The serial port allocation is defined in the file config.c in the project directory.

The following code examples show the allocation of serial ports to the touchscreen controllers supported in the Pluto 6 software libraries:

To assign a serial port to the ELO touchscreen controller:

const ELOCFG EloCfg =
{
    /* FPGA UART 0 serial port */
    &FPUART0Device, 0
};

To assign a serial port to the MicroTouch touchscreen controller:

const MICROTOUCHCFG MicroTouchCfg =
{
    /* DUART serial port channel 0 */
    &DUART0Device, 0
};

It is recommended that the receive buffer size for the serial port assigned to the touchscreen device is increased to a minimum of 64 bytes. This is necessary because, due to the amount of serial data output by the touchscreen device, valid readings may be overwritten. The serial buffer size is defined for each serial port in the file config.c in the project directory. In the following example the DUART receive buffer size is set to 256 bytes:

/* set DUART0 channel 0 Rx buffer to 256 bytes for touchscreen data*/
static BYTE Duart0RxABuffer[1<<8]={0};

Creation of a Calibration Buffer

A calibration buffer needs to be created:

TOUCHCALIBDATA touchscreen_calib_data;

If this buffer is created in the IDRAM OR SYRAM, the calibration of the touchscreen will be preserved on power down otherwise if created in config.c, touchscreen will need to be re- after each power down.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Controller Serial Interfaces

Supported Touchscreen Controller Serial Interfaces

The following Touchscreen Controller serial interfaces are supported in the Pluto 6 Software Libraries:

Manufacturer | Serial Interface
MicroTouch | Serial SMT2 Serial SMT3 Serial SMT3V Serial SMT3R Serial SMT3RV
ELO SmartSet Family | E271-2200 AccuTouch, DuraTouch E211-2210 AccuTouch, DuraTouch E281-2310 IntelliTouch 2500S IntelliTouch

For further information on the above devices, refer to the following manufacturer documentation:

  • MicroTouch Touch Controllers Reference Guide 19-213 V2.2
  • ELO SmartSet Touchscreen Controller Family: Technical Reference Manual V1.0
  • ELO Addendum for E281-2310 Controller
  • ELO Addendum for IntelliTouch 2500S Controller
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Controller Callibration

Touchscreen Controller Calibration

All touchscreens require calibration to ensure correspondence between touch layer co-ordinates and physical display screen co-ordinates.

A generic API function TouchScreenCalibrate() is provided for this purpose, which is used identically for ELO and MicroTouch screens.

A two point calibration sequence is used, which involves the user touching a target near the bottom left of the screen, followed by a target at the top right of the screen. If the display screen has dimensions HSIZE and VSIZE, the targets should be at the following locations:

  • Target 1 (x, y) = ( HSIZE/8 , VSIZE - VSIZE/8 )
  • Target 2 (x, y) = ( HSIZE-HSIZE/8 , VSIZE/8 )

Although the generic API function can be used identically for ELO and MicroTouch screens, the underlying mechanism is different:

  • The MicroTouch Driver uses hardware calibration within the MicroTouch controller. After calibration, the calibration data is stored in non-volatile memory in the MicroTouch controller, and calibration corrections are applied to touch data before it is transmitted to the Pluto 6 system.
  • The ELO driver uses software calibration, with calibration data stored in a structure non-volatile RAM in the Pluto system. The ELO driver applies calibration correction to incoming touch co-ordinate data. If using an ELO touchscreen, the following should be declared in sysram.c in the project directory.
/* Touchscreen calibration data: NOT cleared on power up */
TOUCHCALIBDATA touchscreen_calib_data;

Calibration is only necessary at system installation. Re-calibration should not be necessary unless the display screen size and position are modified.

A code example demonstrating touchscreen calibration using the generic calibration function is listed in the TouchScreenCalibrate() API function documentation.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Controller Modes

Touchscreen Controller Modes of Operation

Serial communication between the touchscreen controller and the Pluto 6 control board operates in two possible modes. The communication mode is set by the TouchScreenCommsMode() function in the generic touchscreen driver API.

Command Mode

This bi-directional communication mode is used for initialising and sending commands to the touchscreen controller. Both the ELO and MicroTouch controllers use a simple <command> <response> protocol. The protocols are implemented in the respective device drivers.

The generic touchscreen API provides the following functions for initialising and sending commands to the touchscreen controller:

API Function | Description
TouchScreenReset() | Resets the Touchscreen Controller.
TouchScreenInit() | Initialises the Touchscreen Controller.
TouchScreenIdentity() | Identify the Touchscreen Hardware.
TouchScreenSetSerial() | Set the Touchscreen serial parameters.
TouchScreenCommsMode() | Set the Touchscreen communications mode.
TouchScreenSetMode() | Set the reporting mode for the Touchscreen Controller.
TouchScreenCalibrate() | Calibrate the Touchscreen Controller.

All of the above functions are not re-entrant. They should only be called from main line code and not from interrupt service routines. All of the above functions expect a response from the Touchscreen Controller, and terminate with a timeout error if no response is received.

Touch Data Mode

In this mode of operation the assigned serial port receives a continuous stream of serial touch data from the touchscreen controller.

When the driver for a touchscreen controller is installed (ELO or MicroTouch) the appropriate 10ms interrupt service routine is installed to perform the following operations:

  • Read incoming touch data packets from the serial receive buffer
  • Convert the touch data packets into a standard format TOUCHDATA record
  • Store the TOUCHDATA records in the buffer TouchDataBuffer[]

The TouchDataBuffer[] used to store the TOUCHDATA records is defined in the file config.c in the project directory. The buffer size must be a power of two. The buffer is circular so the oldest record is overwritten on overflow. A buffer size of n records will contain the last n-1-- TOUCHDATA records.

The following example defines a TouchDataBuffer with 256 entries:

/* touch packet data buffer with 256 entries */
TOUCHDATA	TouchDataBuffer[1<<8]={0};
const	WORD	TouchDataBufferMask=(1<<8)-1;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Defined Values

The following values are defined for use with the generic Touchscreen driver:

Command Mode Defined Values

Label | Meaning
COMMAND_MODE | Bi-directional communication mode to allow initialisation and commands to sent to the touchscreen controller using a command/response protocol. Functions using this mode are executed from main line code and the controller is polled for a response.
TOUCH_DATA_MODE | Uni-directional communication to allow data to be streamed from the touchscreen controller to the Pluto 6. Data capture in this mode is achieved in an interrupt service routine, with the driver controlling the data packet buffer where the data is stored.

Reporting Mode Defined Values

Label | Meaning
DOWN_REPORT | Enable reporting of screen touch down events.
STREAM_REPORT | Enable reporting of continuous stream event data.
UP_REPORT | Enable reporting of screen touch up events.

Touch Packet Status Defined Values

The following values are used to represent the event status in a touch data packet returned from the Touchscreen Controller:

Label | Meaning
DOWN_EVENT | Touch down event.
STREAM_EVENT | Continuous touch event.
UP_EVENT | Lift up event.

Reset Defined Values

The following defined values can be used with the TouchScreenReset() function in the generic Touchscreen API:

Label | Meaning
HARD_RESET | Full hardware reset.
SOFT_RESET | Software reset.

API Function Return Codes

A return value of zero indicates that the function was successfully executed, a non-zero value indicates a communications error:

ELO Communication Return Codes | Meaning
ELO_COMMS_OK | The communication was successful.
ELO_COMMS_FAIL | The communication failed.
ELO_COMMS_TIMEOUT | The attempted communication timed out.
ELO_COMMS_CHECKSUM_ERROR | The data check sum failed.
ELO_COMMS_PROTOCOL_ERROR | A protocol error occurred.
ELO_ACKNOWLEDGE_ERROR | An attempted communication was not acknowledged.

MicroTouch Communication Return Codes | Meaning
MICROTOUCH_COMMS_OK | The communication was successful.
MICROTOUCH _COMMS_FAIL | The communication failed.
MICROTOUCH _COMMS_TIMEOUT | The attempted communication timed out.
MICROTOUCH _COMMS_INVALID_RESPONSE | An invalid response was received from the Touchscreen Controller.

Serial Port Setting Parameter Values

The following settings can be used to configure the touchscreen controller serial port for the devices indicated:

Data Rate
Parameter | Meaning
BAUD1200 | 1200 Baud rate (MicroTouch only)
BAUD2400 | 2400 Baud rate (MicroTouch only)
BAUD4800 | 4800 Baud rate (MicroTouch only)
BAUD9600 | 9600 Baud rate (ELO, MicroTouch )
BAUD19200 | 19200 Baud rate (ELO, MicroTouch)
Data Rate
Parameter | Meaning
BITS7 | 7 data bits (ELO, MicroTouch)
BITS8 | 8 data bits (ELO, MicroTouch)
Stop Bits
STOP1 1 | stop bit (ELO, MicroTouch)
STOP2 | 2 stop bits (ELO, MicroTouch)
Parity Setting
PARITYEVEN | Even parity (ELO, MicroTouch)
PARITYODD | Odd parity (ELO, MicroTouch)
PARTIYNONE | No parity (ELO, MicroTouch)
Handshaking
0 | No handshaking (ELO only)
1 | Handshaking enabled (ELO only)
Note: Handshaking parameter is not used by the MicroTouch controller.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Touchscreen Defined Data Types

The following data types are defined for use with the generic touchscreen driver:

Touchscreen Identity

The following data structure is used to store the controller identity information:

typedef struct touchidentity
{
    BYTE model[32];
    BYTE revision[32];
    BYTE features[32];
    BYTE status[32];
}TOUCHIDENTITY;

The components of the touch identity structure represent the following information:

model | Touchscreen controller model.
revision | Revision version of the model.
features | Special features of the controller.
status | Status of the controller.

Generic Touch Data Packet

The following data structure is used to store touch data packets by the generic driver:

typedef struct touchdata
{
    UWORD x;
    UWORD y;
    UWORD z;
    UBYTE status;
}TOUCHDATA;

The components of the touch data packet represent the following information:

x | X touch co-ordinate (unscaled 10 bit value in the range 0 1023).
y | Y touch co-ordinate (unscaled 10 bit value in the range 0 1023).
z | Touch pressure reading (if supported by the hardware).
status | Type of touchscreen event.

Generic Touchscreen Calibration Data

The following data structure is used to store touchscreen calibration data by the generic driver:

typedef struct touchcalibdata
{
    UWORD x[2];
    UWORD y[2];
    UBYTE flag;
} TOUCHCALIBDATA;

The following data is set during calibration:

x[0] | Lower left x screen co-ordinate.
y[0] | Lower left y screen co-ordinate.
X[1] | Upper right x screen co-ordinate.
y[1] | Upper right y screen co-ordinate.
flag | Flag that is set to indicate that calibration has been performed.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


E2ROM Driver
WriteE2Rom Writes a specified number of bytes of data to the given internal address on the EEPROM. ReadE2Rom Reads a specified number of bytes of data from the given internal address on the EEPROM.

The E2ROM driver module provides functions to read from and write data to the EEPROM Device optionally fitted into socket U7 on the Pluto 6 controller board. Communication with the E2ROM uses the I2C protocol provided by the M-Bus driver module.

API Functions

The following API functions are associated with this module:

Function | Description
WriteE2Rom | Writes a specified number of bytes of data to the given internal address on the EEPROM.
ReadE2Rom | Reads a specified number of bytes of data from the given internal address on the EEPROM.

See Also

  • E2ROM Device DriverConfiguration Data
  • E2ROM Device Driver Defined Values
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Write E2ROM API Function

E2ROM Driver

API Function

BYTE WriteE2Rom(const BYTE *src, WORD numbytes, const DEVICE* dev, WORD offset)

Description

Write a specified number of bytes of data to the given internal address on the EEPROM.

Parameters

Parameter | Description
src | Address of the source data
numbytes | Number of bytes to be written
dev | Address of the EEPROM device to use
offset | Internal offset within the EEPROM where the data is to be written to

Return Value

Return E2_PASSED if the write is successful.
Return E2_WRITE_FAILED if the write fails.
Return E2_OUT_OF_BOUNDS if invalid parameters are passed to the function.

Code Example

Write 4 bytes of data from buffer src to the EEPROM at internal offset of 340 bytes.
*/
if(WriteE2Rom(&src, 4, &E2RomDevice, 340) == E2_PASSED)
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Read E2ROM API Function

E2ROM Driver

API Function

BYTE ReadE2Rom(const DEVICE* dev, WORD offset, WORD numbytes, BYTE *dst)

Description

Read a specified number of bytes of data from the given internal ofset on the EEPROM.

Parameters

Parameter | Description
dev | Address of the EEPROM device to use
offset | Internal offset within the EEPROM where the data is to be read from
numbytes | Number of bytes to be read
dst | Address of the destination buffer to read data into

Return Value

Return E2_PASSED if the read is successful.
Return E2_READ_FAILED if the read fails.
Return E2_OUT_OF_BOUNDS if invalid parameters are passed to the function.

Code Example

/*
Read 4 bytes of data from the EEPROM at internal offset of 340 bytes to the buffer dst.
*/

BYTE dst[512];

if(ReadE2Rom(&E2RomDevice, 340, 4, dst) == E2_PASSED)
{
    return(TRUE);
}

/*
Read the entire contents of the EEPROM to the buffer dst.
*/
if(ReadE2Rom(&E2RomDevice, 0, 512, dst) == E2_PASSED)
{
    return(TRUE);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


E2ROM Config Data

E2ROM Device Driver Configuration Data

The E2RCFG structure in the file config.c defines the I2C driver that the E2ROM device uses for communication and the I2C hardware address that is assigned to the E2ROM device. It also defines the retry time and number of retries to try after a failed read/write. The default configuration uses the M-Bus I2C device driver and the I2C hardware address 0xA0, 2x10ms wait after a failed read/write and 1 retry.

const   E2RCFG    E2RomCfg[]=
{
    {
        &MbusDevice,  /* I2C MBUS Device Driver */
        NM24C04,      /* I2C Device address = 0xA0*/
        5,            /* Retry time after failed read/write*/
        1,            /* Retries after failed read/write*/
    }
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


E2ROM Defined Values

The following return values defined in the E2_ERROR_TABLE enumeration are used by the E2ROM Driver:

Label | Meaning
E2_PASSED | Signifies that the operation was successful
E2_READ_FAILED | Signifies that a read operation failed.
E2_OUT_OF_BOUNDS | Signifies that a read or write operation was attempted that exceeded the memory range of the EEPROM device.
E2_WRITE_FAILED | Signifies that a write operation failed.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Customer Peripherals Module

The Custom Peripherals Module allows games developers to create their own drivers and build them into GNU library files for inclusion in game projects. This is useful where a developer needs a driver for a particular device, for example a coin mechanism. The source code is supplied for all drivers in this module, which can be adapted to suit a particular hardware device.

Customer Peripherals Module Components

Component | Description
RM161680 | This is the ramp table and definitions for a Starpoint RM161680 reel and can be used as a template from which to derive ramp tables for other types of reels.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


RM161680 Reel Profile

This module contains the reel profile for a Starpoint RM161680 reel. The profile is used in the reel configuration in the file config.c at project level. The stepper driver uses the profile data to control the reels.

The profile contains the following data:

Pattern Tables

Pattern tables are specified to send to the stepper motors to perform full and half steps.

Vector Tables

Vector tables of functions are provided for operations such as spinning, nudging and wobbling reels.

Ramp Tables

Ramp and ramp delay tables are provided for reel operation.

Reel Type Definition

A REEL_TYPE structure is populated with the reel specific data.

See Also

  • Stepper Configuration Data
  • Stepping Motor Profiles
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Software

Stepper Configuration Data

The following data related to the Stepper Device Driver is user configurable and is contained in the config.c file at game level.

For each reel that the game application uses the following data must be set:

/* Reel 1 */
/* clear stepper variables */

STEPPERVARS reel1_ram =
{
    0,0,     /* Set position/index */
    0,       /* Direction */
    0,0,     /* Pattern table/index */
    0,       /* Vector table */
    0,0,0,   /* Delay table index timer */
    0,0,     /* Pix mask/opto count */
    0,0,     /* Spin/enable flags */
    0,0      /* Pos correction/tab missed */
};

STEPPERZVARS reel1_ram2;

/* set the inputs and outputs */
const REEL_ADDR reel1_addr =
{
    REEL1_OPS,
    REEL1_IP
};

/* configure the reel - in this case using the RM161680 ramp tables */
const STEPPER reel1 =
{
    &reel1_addr,
    &RM161680,
    &reel1_ram,
    &reel1_ram2,
    0
};

Once all of the reels have been configured they must be a added to the stepper list. In the example code below four reel steppers were previously defined and are used to create the stepper list.

/* create a list of all of the stepper devices */
const	STEPPER* const	stepperlist[]=
{
&reel1,
    &reel2,
    &reel3,
    &reel4,
    EOF_STEPPERS
};

Each member of the stepper list is then configured:

/* configure the steppers in the list */
const	STEPCFG StepperCfg=
{
    stepperlist,
    5,	/* No. of steps to wake up steppers */
    50,	/* delay between steps */
    50	/* opto delay */
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Software

Stepping Motor Profiles

Overview

The generic stepper motor driver will typically be used to control reels and can handle many different types of reel. There is no limit in the software to the number of reels or the number of different types of reel that can be controlled simultaneously.

All the information defining a particular reel type is contained in a REEL_TYPE structure. An example of a reel structure is in the Custom Peripheral driver library and it is suggested that any new reel types defined be added to this library. (libcustomperipherals.a) The example reel type is a Starpoint RM161680.

Defining a New Reel Type

The type declaration for the REEL_TYPE structure in stepper.h should be used when defining a new type structure.

typedef	struct reel_type
{
    WORD		steps_per_rev;
    WORD		steps_per_symbol;
    BYTE		min_opto;
    BYTE		tolerance;
    BYTE		revpos;
    const RAMP	*ramps[MAX_RAMPS];
} REEL_TYPE;

steps_per_rev
The number of stepper motor steps required to move the reel one complete revolution.

steps_per_symbol
The number of stepper motor steps required to move the reel one whole reel symbol.

min_opto
The number of times the position sensor must be seen during one step to activate the position correction software.

tolerance
This is the size of the position error in motor steps, which is allowable without activating the position correction software.

revpos
This should be set TRUE if the position detection software is to be active whilst the reel is spinning backwards. This position correction software is always active whilst the reel is spinning forwards.

ramps
This is a list of pointers to RAMP structures. A RAMP structure contains all the information required to define a particular type of reel movement. There are two ramps for system use, ‘system’ and ‘initialisation’ ramps, In addition there are ramps for spinning at 69RPM, 78RPM, 89RPM, 96RPM, and 104RPM.There is provision for three different nudge ramps and three different ‘skill stop’ ramps.

The RAMP Structure

The RAMP structure allows the stepper driver to be very flexible in the way it can control the reels. A RAMP structure can be defined to make a reel do almost anything.

typedef	struct ramp
{
    const WORD	*pattern_tbl;
    WORD		pixmask;
    void		(*const *vector_tbl)(const void*);
    const WORD	*delay_lst;
} RAMP;

pattern_tbl
The pattern table defines the energising sequence of the four phases of the stepper motor. To move one step the reel increments its index into this table and writes the new pattern out to the motor coils.

pixmask
Each time the pattern table index is incremented (or decremented for reverse spin) it is logically ANDed with this value to wrap it around at the end of the table.

vector_tbl
This is a list of function pointers to the functions, which will be called by the stepper driver in order to control the reel. The standard vector tables provided will suffice for most situations but for any special requirements a new vector table may be defined and new functions written.

delay_lst
A list of delays (in milliseconds) required to time the various steps. The vector functions will access these delays and the meaning of any particular delay is dependant on the vector functions used and the number of steps controlled by each vector function. For the standard vector functions (RampUp, Run, and RampDown) the first number indicates the number of steps to be controlled by that vector function and that is followed by the a delay for each step. It is left to the vector functions to manipulate the index into this delay list.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Standard Interface Module

This module provides interface drivers which use the services of lower level device drivers. The drivers provide a simple interface to allow the game developer to perform the following tasks:

  • Access a file system on an ATA device
  • Load audio samples from an ATA device
  • Load graphics files from an ATA device.

Standard Interface Module Components

Component | Description
FAT32 Driver | The FAT32 driver provides an API to allow the developer to access files stored on an ATA device formatted with a FAT32 file system.
Streamed Audio Driver | The Streaming Audio driver provides an API to allow the developer to stream audio files in.wav format from an ATA device.
HSF Audio Driver | The Heber Sound File Audio driver provides an alternative API to allow the developer to stream audio files in a custom .hsf format from an ATA device with less CPU overhead on the Pluto 6.
Microsoft® Windows® BMP Bitmap Graphics File Loader | The Microsoft® Windows® BMP bitmap graphics file loader allows the developers to load .bmp format graphics files from an ATA device to video memory.
TGA Bitmap Graphics File Loader | The TGA bitmap graphics file loader allows the developers to load .tga format graphics files from an ATA device to video memory.
Heber Image Format Graphics File Loader | The Heber Image Format (HIF) graphics file loader allows the developers to load .hif format graphics files from an ATA device to video memory.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FAT32 Driver

This driver allows read/modify access to a FAT32 file system on an external ATA device.
Examples of possible devices are:

  • IDE Hard Drive connected using an IDE cable to connector P5 on the Pluto 6 board
  • Compact Flash Card in connector P6 on the Pluto 6 board.

If the drive is partitioned, the FAT32 file system to be accessed must be on the Primary Partition.

API functions are provided to:

  • find and mount the file system
  • navigate the directory structure
  • list directory the contents
  • load a file from the drive into memory
  • read a sector (512 bytes) from a file
  • read a character from a file
  • modify an existing file sector

Note: This driver uses the services of the ATA Device Driver. This driver must be loaded, and the drive initialised before the services of the FAT32 driver can be used. For further information on the ATA driver refer to the ATA driver documentation.

The FAT32 driver uses file descriptors to allow a particular file to be accessed. A file descriptor structure is populated when a file is opened, and this is used as a reference for operations involving that file. For further information on file descriptors refer to the FAT32 File Descriptors page.

API Functions

The following API functions are associated with this module:

Function | Description
MountFAT32 | Mounts and initialise a FAT32 file system.
ChangeDir | Changes current directory to new directory.
NextDirRecord | This function reads a single record from the current directory.
DirEntryLongfilename | Gets a pointer to the start of the long file name in a directory entry.
DirEntryAlias | Gets a pointer to the start of the short 8.3 format filename string in a directory entry.
DirEntryAttrib | Gets a pointer to the start of the attribute bit string in a directory entry.
DirEntryFilesize | Gets the file length in bytes from a directory entry.
GetDir | Returns current directory path string.
FAT32LoadFile | Loads a file into system or video memory.
FileOpen | Opens file from ATA device.
FileClose | Closes a given file.
FileRewind | Returns to the start of a given file.
FileGetChar | This function provides character oriented file access.
FileLoad | Loads a binary image file, previously opened with FileOpen function, into system or video RAM.
FileGetSectors | This function provides block oriented file access.
FilePutSector | This function overwrites the current sector of the specified file.
FileSeekSector | This function sets the file current sector to offset.
FileCurrentSector | This function enhances block oriented file writing by returning the current position of the file descriptor.

See Also

  • FAT32 File Descriptors
  • FAT32 Defined Values
  • FAT32 Defined Data Structures
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Mount FAT32 API Function

FAT32 Driver

API Function

UBYTE MountFAT32(const DEVICE *dev)

Description

Look for a FAT32 file system on primary partition of the drive. Mount the file system and initialise the file system structure.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.

Return Value

Returns zero on success.
Returns non-zero on failure.

Code Example

/* Mount FAT32 Filesystem on an ATA device */
DriveSpinup(&ATADevice);
TxString(&SerialDevice,1,"Mounting Drive...\r\n");

if (MountFAT32(&ATADevice) != 0)
{
    TxString(&SerialDevice,1,"Failed to mount drive\r\n");
    DriveSpindown(&ATADevice);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Change Directory API Function

FAT32 Driver

API Function

UBYTE ChangeDir(const DEVICE *dev, BYTE *path)

Description

Change current directory to new directory. The new directory is root, parent or single level sub directory of current directory.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
path | New directory name string.

Return Value

Returns zero if successful.
Returns non-zero if new directory not found.

Code Example

/* Change to root directory */
ChangeDir(&ATADevice, “\\”);

/* Change to parent directory */
ChangeDir(&ATADevice, “..”);

/* Change to current directory: no change */
ChangeDir(&ATADevice, “.”);

/* Change to sub-directory “images” */
ChangeDir(&ATADevice, “images”);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Next Directory Record API Function

FAT32 Driver

API Function

UBYTE NextDirRecord(const DEVICE* dev, DIR_ENTRY *dir_entry);

Description

This function reads a single record from the current directory. The structure dir_entry is initialised with the record data, and can be interrogated by the functions:

  • DirEntryLongfilename
  • DirEntryAlias
  • DirEntryAttrib
  • DirEntryFilesize

The function will increment the directory record pointer to next record in the current directory, until the end of the current directory is reached. Thus, the entire current directory can be listed by repeatedly calling this function.

The directory record pointer is initialised to the first record in the directory by function ChangeDir().

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
dir_entry | Address of the structure holding directory record data: filename, filesize, attribute bits.

Return Value

Returns true if there are further records in the directory.
Returns false if there are no more directory records and the end of the directory has been reached.

Code Example

/* declare a directory entry variable */
DIR_ENTRY entry;

/*
initialise current directory structure and directory record pointer
*/
ChangeDir(&ATADevice, ".");

/* loop through the records in the directory */
while (NextDirRecord(&ATADevice, &entry))
{

}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Long File Name API Function

FAT32 Driver

API Function

UBYTE *DirEntryLongfilename(const DEVICE *dev, DIR_ENTRY *dir_entry)

Description

Returns a pointer to the start of the string containing the directory entry long file name.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
dir_entry | Address of the structure holding directory record data: filename, filesize, attribute bits.

Return Value

Returns a pointer to the start of the string containing the directory entry long file name.

Code Example

/* declare a directory entry variable */
DIR_ENTRY entry;

/* declare an array of bytes to hold the file name */
BYTE str[256];

/*
initialise current directory structure and directory record pointer
*/
ChangeDir(&ATADevice, ".");

/* loop through the records in the directory */
while (NextDirRecord(&ATADevice, &entry))
{
    sprintf(str, “%s\r\n", DirEntryLongfilename(&ATADevice, &entry));
    TxString(&SerialDevice,1,str);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Short File Name API Function

FAT32 Driver

API Function

UBYTE *DirEntryAlias(const DEVICE *dev, DIR_ENTRY *dir_entry)

Description

Get a pointer to the start of the short 8.3 format filename string in a directory entry.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
dir_entry | Address of the structure holding directory record data: filename, filesize, attribute bits.

Return Value

Returns a pointer to the start of the string containing the short 8.3 format filename string.

Code Example

/* declare a directory entry variable */
DIR_ENTRY entry;

/* declare an array of bytes to hold the short file name */
BYTE str[256];

/*
initialise current directory structure and directory record pointer
*/
ChangeDir(&ATADevice, ".");

/* loop through the records in the directory */
while (NextDirRecord(&ATADevice, &entry))
{
    sprintf(str, “%-12s\r\n", DirEntryAlias(&ATADevice, &entry));
    TxString(&SerialDevice,1,str);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Directory Entry Attribute

FAT32 Driver

API Function

UBYTE *DirEntryAttrib(const DEVICE *dev, DIR_ENTRY *dir_entry)

Description

Get a pointer to the start of the attribute bit string in a directory entry.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
dir_entry | Address of the structure holding directory record data: filename, filesize, attribute bits.

Return Value

Returns a pointer to the start of the directory entry attribute bit string.

Code Example

/* declare a directory entry variable */
DIR_ENTRY entry;

/* declare an array of bytes to hold the attribute bit string */
BYTE str[256];

/*
initialise current directory structure and directory record pointer
*/
ChangeDir(&ATADevice, ".");

/* loop through the records in the directory */
while (NextDirRecord(&ATADevice, &entry))
{
    sprintf(str, “%8s\r\n", DirEntryAttrib(&ATADevice, &entry));
    TxString(&SerialDevice,1,str);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Directory Entry File Size API Function

FAT32 Driver

API Function

ULONG DirEntryFilesize(const DEVICE *dev, DIR_ENTRY *dir_entry)

Description

Get the file length in bytes from a directory entry.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
dir_entry | Address of the structure holding directory record data: filename, filesize, attribute bits.

Return Value

Returns the length of the file in bytes.

Code Example

/* declare a directory entry variable */
DIR_ENTRY entry;

/* declare an array of bytes to hold the file length */
BYTE str[256];

/*
initialise current directory structure and directory record pointer
*/
ChangeDir(&ATADevice, ".");

/* loop through the records in the directory */
while (NextDirRecord(&ATADevice, &entry))
{
    sprintf(str, “%10d bytes\r\n", DirEntryFilesize(&ATADevice, &entry));
    TxString(&SerialDevice,1,str);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Current Directory Path API Function

FAT32 Driver

API Function

UBYTE *GetDir(const DEVICE *dev)

Description

Returns current directory path string.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.

Return Value

Returns current directory path string. This is full absolute directory path.

Examples:
“\”
“\images”
“\images\playing_cards”

Code Example

/* declare an array of bytes to hold the path string */
BYTE str[256];

sprintf(str, "%s", GetDir(&ATADevice));
TxString(&SerialDevice,1,str);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load File API Function

FAT32 Driver

API Function

UBYTE FAT32LoadFile(const DEVICE *dev, BYTE *path, UWORD *mem)

Description

Binary transfer from file path to memory at mem in System or Video RAM. The file to be transferred must be in the current directory.

NOTE: An integer number of sectors are transferred. Each sector contains 512 bytes. The total number of bytes transferred may therefore exceed the number of bytes in the file by up to 512 bytes.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
path | Filename string of file to be transferred. This must be in the current directory. Filename can be: FAT32 long format, or short (8.3) format. Example: “acespades playing card” or “acespa~1”.
mem | Pointer to memory address to which the data is transferred. This can be in System RAM or Video RAM.

Return Value

Returns zero if successful.
Returns non-zero if file not found.

Code Example

/*
Navigate filesystem, load image file and display
Image to be loaded is: \images\playing_cards\acespa~1.bin
*/

/* change directory */
ChangeDir(&ATADevice, "\\");

if(ChangeDir(&ATADevice, "images") != 0)
{
    TxString(&SerialDevice,1,"\r\nDirectory not found.\r\n");
}

if (ChangeDir(&ATADevice, "playing_cards") != 0)
{
    TxString(&SerialDevice,1,"\r\nDirectory not found.\r\n");
}

/* load file to undisplayed video memory and blit to screen */
if(!FAT32LoadFile(&ATADevice, “acespa~1.bin”,(UWORD *)offscreen))
{
    PutSprite(screen0, 0, 0, HSIZE, offscreen, card_xsize, card_ysize,
    0, BYTES_PER_PIXEL);
}
else
{
    TxString(&SerialDevice,1,"\r\nFile not found.\r\n");
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Open API Function

FAT32 Driver

API Function

FILE_DESCRIPTOR *FileOpen(const DEVICE *dev, BYTE *filename, FILE_DESCRIPTOR *file, UBYTE mode)

Description

Open a given file on an ATA device. Initialise the file pointer structure FILE_DESCRIPTOR.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
filename | Filename string of file to be transferred. This must be in the current directory. The filename can be: FAT32 long format, or short (8.3) format. Example: “acespades playing card” or “acespa~1”.
file | Pointer to the file descriptor.
mode | Current options: READ_ONLY - open file for reading. OVERWRITE_ONLY - open file for over-writing. READ_OVERWRITE - open file for reading/ over-writing.

Return Value

Return pointer to file descriptor.
Return NULL pointer on failure.

Code Example

/* change directory to the root directory */
ChangeDir(&ATADevice, "\\");
/* change directory to the sub-direcctor “images” *\
ChangeDir(&ATADevice, "images");

/* open a binary file called “image.bin” *\
if(FileOpen(&ATADevice, “image.bin”, &file[0], READ_ONLY) == NULL)
{
    /* file not found so output an error message */
    TxString(&SerialDevice,1,"\r\nFile not found.\r\n");
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Close API Function

FAT32 Driver

API Function

UBYTE FileClose(const DEVICE *dev, FILE_DESCRIPTOR *file)

Description

Close a given file.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the file to be closed.

Return Value

Not used.

Code Example

/* close the first file in the file descriptor list “file” */
FileClose(&ATADevice, &file[0]);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Rewind File API Function

FAT32 Driver

API Function

UBYTE FileRewind(FILE_DESCRIPTOR *file)

Description

Return to the start of an open file.

Parameters

Parameter | Description
file | Pointer to the open file.

Return Value

Not used.

Code Example

/* rewind to the start of the first file in the file descriptor list “file” */
FileRewind(&file[0]);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Character Access API Function

FAT32 Driver

API Function

UWORD FileGetChar(const DEVICE *dev, FILE_DESCRIPTOR *file)

Description

This function provides character oriented file access. A single character is read from current reading position in the file. One sector (512 bytes) of data is buffered in a buffer within the statically declared file descriptor structure.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the open file.

Return Value

Returns the next character from the file.
Returns EOF at end-of-file or failure.

Code Example

/* variable to hold the character read from the file */
UWORD ch;

/* open a file */
FileOpen(&ATADevice, “msg.txt”, &file[0], READ_ONLY);

/*
read each character in the until the end of the file or an error occurs
*/
while((ch= FileGetChar(&ATADevice, &file[0])) != EOF)
{
    /* output the character to a serial port */
    TxChar(&SerialDevice, 1, (UBYTE) ch );
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Load API Function

FAT32 Driver

API Function

UBYTE FileLoad(const DEVICE* dev, FILE_DESCRIPTOR *file, UWORD *mem)

Description

Binary transfer from file to memory at mem in System or Video RAM. The file must previously have been successfully opened with function FileOpen().

Note: An integer number of sectors are transferred. Each sector contains 512 bytes. The total number of bytes transferred may therefore exceed the number of bytes in the file by up to 512 bytes.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the open file.
mem | Pointer to memory address to which the data is transferred. This can be in System or Video RAM.

Return Value

Returns zero if successful.
Returns non-zero if file not open.

Code Example

/*
Navigate filesystem, open binary image file, load to video memory

Image to be loaded is: \images\ace.bin
*/
FILE_DESCRIPTOR image_file;

/* change directory */
ChangeDir(&ATADevice, "\\");

if(ChangeDir(&ATADevice, "images") != 0)
{
    TxString(&SerialDevice,1,"\r\nDirectory not found.\r\n");
}

/* open file */
if(FileOpen(&ATADevice, "ace.bin", &image_file, READ_ONLY) == NULL)
{
    TxString(&SerialDevice,1,"\r\nFile not found.\r\n");
}

/* load file to undisplayed video memory */
FileLoad(&ATADevice, &image_file, (UWORD *)offscreen))
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Sector Access API Function

FAT32 Driver

API Function

ULONG FileGetSectors(const DEVICE *dev, FILE_DESCRIPTOR *file, UWORD *mem, ULONG nsectors)

Description

This function provides block oriented file access. Read n sectors of data from the file at the current reading position to a buffer. (One sector = 512 bytes).

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the file to be read from.
mem | Pointer to memory buffer to which data will be loaded.
nsectors | Number of sectors of data to be loaded.

Return Value

Returns number of sectors read.

Code Example

/* animation */
if (FileOpen(&ATADevice, "animation.bin", &file[0], READ_ONLY) != NULL)
{
    /* each animation frame occupies 258 sectors */
    while (FileGetSectors(&ATADevice,
           &file[0],(UWORD*)(VideoMemBase+offscreen), 258))
    {
        PutSprite(screen1, 0, 0, offscreen, width, height, 0, 2);
    }
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Put Sector API Function

FAT32 Driver

API Function

ULONG FilePutSector(const DEVICE *dev, FILE_DESCRIPTOR *file, UWORD *mem)

Description

Overwrites the current sector of the specified file. The current sector is specified by the file descriptor current_sector field. The current sector is incremented after writing.

If the file mode is READ_ONLY, the sector is not written and the function returns an error code.

Notes

This function allows modification of existing files. No change in file size is possible.

Mem is a pointer to the data to be written. 512 bytes of data (256 words) will be written to the disk.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the open file.
mem | Pointer to memory buffer from which data will be written.

Return Value

Returns zero if successful.
Returns non zero on failure with one of the following error codes:

FILE_NOT_OPEN
FILE_READ_ONLY

Code Example

/* logfile */
/* buffer for log data before writing to disc */
UWORD logdata[256];

/* fill the buffer with something useful… */

if (FileOpen(&ATADevice, "log.txt", &file[0], READ_OVERWRITE) != NULL)
{
    /* move file position to end of file*/
    FileSeekSector(&ATADevice, &file[0], (file[0]. size - 1) /BYTES_PER_SECTOR);

    /* write the log data to the end of the file */
    FilePutSector(&ATADevice, &file[0], logdata);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Seek Sector API Function

FAT32 Driver

API Function

UWORD FileSeekSector (const DEVICE *dev, FILE_DESCRIPTOR *file, ULONG offset)

Description

Sets the file current sector to offset.

First sector in file has offset=0

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the open file.
offset | Sector offset position, starting at zero.

Return Value

Returns zero if successful, otherwise one of the following error codes:

FILE_NOT_OPEN
FILE_SECTOR_OUT_OF_RANGE

Code Example

/* Over write the tenth sector in file
*/

FILE_DESCRIPTOR *destfile;
SECTORDATA buffer;
LONG sector = 10;

if(FileOpen(&ATADevice, "destfile.txt", &destfile, READ_OVERWRITE) == NULL)
    TxString(&SerialDevice,0,"File not found: destfile.txt\r\n");

SomeFunction(&buffer);	/* fill buffer */

if(FileSeekSector(&ATADevice, &destfile, sector-1 ) == 0)
{
    FilePutSector(&ATADevice, &dest, buffer.bw);
    TxString(&SerialDevice,0,”Sector written”);
}
else
{
    TxString(&SerialDevice,0,”Write Failed”);

}
FileClose(&destfile);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


File Current Sector API Function

FAT32 Driver

API Function

ULONG FileCurrentSector(const DEVICE *dev, FILE_DESCRIPTOR *file)

Description

This function enhances block oriented file writing by returning the current position of the file descriptor.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.
file | Pointer to the file descriptor for the file.

Return Value

Returns the current file position as an offset in sectors from the beginning of the file.

Code Example

/* logfile */
ULONG current_pos;

if (FileOpen(&ATADevice, "log.txt", &file[0], READ_OVERWRITE) != NULL)
{

    /* access sectors on the file… */

    /* move file position to end of file*/
    Current_pos = FileCurrentSector(&ATADevice, &file[0]);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FAT32 File Descriptors

File descriptors are used as a reference to access files in the FAT32 file system. The file descriptor structure is populated when a file is opened and holds data relating to the file name, path and location on the drive.
The following functions use file descriptors:

Function | Description
FileOpen() | Open a file and populate the file descriptor.
FileGetChar() | Get a single character from an open file.
FileGetSectors() | Get a specified number of sectors of data from an open file.
FileRewind() | Return the file pointer to the start of an open file.
FileClose() | Close an open file.

The number of available file descriptors limits the number of files that can be open at one time; one file descriptor is required for open each file. File descriptors are statically declared by the game developer and not dynamically allocated. It should be noted that each file descriptor requires 1810 bytes of data. The number of file descriptors that can be declared is restricted by the amount of available system RAM. The available file descriptors are declared in the file config.c.

Code Example

/* define a value for the maximum number of open files */
#define MAX_OPEN_FILES 8

/* declare an array of file descriptors */
FILE_DESCRIPTOR file[MAX_OPEN_FILES];
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FAT32 Defined Types

The following types are defined for use with the FAT32 device driver:

File System Types

Defined Type | Description
FILESYSTEM_UNKNOWN | Unknown file system.
FILESYSTEM_FAT12 | FAT12 file system.
FILESYSTEM_FAT16_MAX32M | FAT 16 file system.
FILESYSTEM_EXTMSDOS_NOTLBA | Extended MS DOS not logical block address.
FILESYSTEM_FAT16_NOTLBA | FAT 16 not logical block address.
FILESYSTEM_FAT32_NOTLBA | FAT 32 not logical block address.
FILESYSTEM_FAT32 | FAT 32.
FILESYSTEM_FAT16 | FAT 16.
FILESYSTEM_EXTMSDOS | Extended MS DOS.

File Status

Defined Type | Description
FILE_OPEN | File open.
FILE_CLOSED | File closed.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


FAT32 Defined Data Structures

The following data structures are defined for use with the FAT32 device driver:

File System Descriptor

The file system descriptor structure is used to hold information on a file system:

/* file system descriptor */
typedef struct
{
    UBYTE status;
    UBYTE label[12];
    ULONG partition_size;
    UBYTE sectors_per_cluster;
    ULONG FAT_start_sector;
    ULONG data_start_sector;
    ULONG root_dir_start_cluster;
    ULONG current_dir_start_cluster;
    UBYTE current_path[256];
} FILESYSTEM_DESCRIPTOR;

Directory Descriptor

The directory descriptor structure is used to hold information on directory:

/* directory descriptor */
typedef struct
{
    ULONG next_cluster;
    ULONG next_record;
} DIR_DESCRIPTOR;

Directory Entry

The directory entry structure is used to hold information on directory:

/* directory entry */
typedef struct
{
    UBYTE alias[16];
    UBYTE long_filename[256];
    ULONG filesize;
    UBYTE attrib_str[16];
} DIR_ENTRY;

File Descriptor

The file descriptor structure is used to hold information on an open file:

/* file descriptor */
typedef struct
{
    /* Start cluster on drive */
    ULONG start_cluster;
    /* Cluster List */
    RLE_CLUSTER_LIST cluster_list;
    /*
    Current byte position (file relative)  0 <= current_byte < size
    */
    ULONG current_byte;
    /* Current sector (file relative) = current_byte/512 */
    ULONG current_sector;
    /* Sector Buffer (512 bytes) */
    SECTORDATA buffer;
    /* File size in bytes */
    ULONG size;
    /* Open/Closed */
    UBYTE status;
    /* Future expansion (eg R, RW, contiguous) */
    UBYTE flags;
} FILE_DESCRIPTOR;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Driver

The Streamed Audio Driver provides the capability to stream up to 4 channels of audio from a Compact Flash card. The driver will stream 16kHz and 32kHz mono and stereo files in .wav format.

The driver supports the following .wav file formats:

  • 16-bit uncompressed PCM
  • 8-bit uncompressed PCM
  • 8-bit U-Law compressed PCM
  • 8-bit A-Law compressed PCM.

API Functions

The following API functions are associated with this module:

Function | Description
InitStreamedAudio | This function initialises the Streamed Audio driver.
InitWavFile | This function prepares a .wav file for playback.
PlaybackCachedWavFile | This function plays back a specified WAV file on a specified audio channel.
QuietChannel | This function stops any currently playing .wav files on a specified audio channel and closes the audio channel and rewinds the audio file.
StopAudioChannel | This function stops any currently playing .wav files on a specified audio channel and rewinds the audio file.
SetAudioVolume | This function sets the volume on a specified channel.
SoundChannelBusy | This function checks to see if an audio sample is currently playing on a specified channel.
SearchForWAVFile | This function prepares a WAV file for playback using the function PlaybackWavFile().
PlaybackWAVFile | This function plays back the specified WAV file on the specified channel.

See Also

  • Streamed Audio Defined Data Structures
  • Streamed Audio Defined Values
  • Streamed Audio Format Considerations
  • Streamed Audio Sample Preparation
  • Streamed Audio Driver Recommended Usage
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Initialise Audio Driver API Function

Streamed Audio Driver

API Function

void InitStreamedAudio( const DEVICE *dev )

Description

This function initialises the streamed audio driver, and must be called before any other streamed audio API functions are called.

Parameters

Parameter | Description
dev | Address of the ATA device. This will be &ATADevice.

Return Value

None.

Code Example

/* Initialise streamed audio driver */
InitStreamedAudio(&ATADevice);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Initialise Audio File API Function

Streamed Audio Driver

API Function

void InitWavFile( BYTE *filename, WAVFILEINFO *wavFileInfo )

Description

This function prepares a WAV file for playback using the function PlaybackCachedWavFile().

Parameters

Parameter | Description
filename | .wav file name on the Compact Flash Card.
wavFileInfo | Structure containing .wav file information.

Return Value

None.

Code Example

/* Prepare WAV file */
WAVFILEINFO wavFile;

InitWavFile( “music.wav”, &wavFile );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Play Audio File API Function

Streamed Audio Driver

API Function

void PlaybackCachedWavFile( BYTE channel, WAVFILEINFO *wavFileInfo )

Description

This function plays back the specified WAV file on the specified channel. The WAV file must be prepared using the function InitWavFile() first.

Parameters

Parameter | Description
channel | Output audio channel. Refer to the Streamed Audio Driver Defined Values page for the defined channels.
wavFileInfo | Structure containing .wav file information.

Return Value

None.

Code Example

/* Play WAV file on left channel 0 */
PlaybackCachedWavFile( AUDIO_LEFT0, &wavFile );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Quiet Channel API Function

Streamed Audio Driver

API Function

void QuietChannel( BYTE audioChannel )

Description

Stops any currently playing WAV files on the specified audio channel and closes the files.

Parameters

Parameter | Description
audioChannel | Audio channel to silence. Refer to the Streamed Audio Driver Defined Values page for the defined channels.

Return Value

None.

Code Example

/* Stop any currently mixed playing samples and closes the files */
QuietChannel( AUDIO_STEREO1 );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Volume API Function

Streamed Audio Driver

API Function

void SetAudioVolume( BYTE audioChannel, BYTE volume )

Description

Sets the volume on the specified channel. The volume ranges from 0 (silent) to 255 (maximum). However there are only 16 discrete volumes (e.g. 0, 16, 32 , 224, 240).

Parameters

Parameter | Description
audioChannel | Audio channel to silence. Refer to the Streamed Audio Driver Defined Values page for the defined channels.
volume | New volume.

Return Value

None.

Code Example

/* Sets volume to 96 on right channel */
SetAudioVolume( AUDIO_RIGHT0, 96 );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Sound Channel Busy API Function

Streamed Audio Driver

API Function

BYTE SoundChannelBusy( BYTE audioChannel )

Description

Checks to see if an audio sample is currently being played on a specified channel.

Parameters

Parameter | Description
audioChannel | Audio channel to silence. Refer to the Streamed Audio Driver Defined Values page for the defined channels.

Return Value

Returns 0 if no audio playing.
Returns 1 if audio currently playing.

Code Example

/* Checks if WAV is playing on right channel 1 */
BYTE isBusy;
isBusy = SoundChannelBusy( AUDIO_RIGHT1 );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Search for WAV File API Function

Streamed Audio Driver

API Function

BYTE SearchForWavFile( BYTE *filename, FILE_DESCRIPTOR *file )

Description

This function prepares a WAV file for playback using the function PlaybackWavFile().

Parameters

Parameter | Description
filename | .wav file name on the Compact Flash card.
file | Uninitialised file descriptor structure.

Return Value

0 on success, INITERR_FILENOTFOUND on failure.

Code Example

/* Prepare WAV file */
FILE_DESCRIPTOR wavFile;

SearchForWavFile( “music.wav”, &wavFile );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Playback WAV File API Function

Streamed Audio Driver

API Function

BYTE PlaybackWavFile( BYTE channel, FILE_DESCRIPTOR *file )

Description

This function plays back the specified WAV file on the specified channel. The WAV file must be prepared using the function SearchForWavFile() first.

Parameters

Parameter | Description
channel | Output audio channel. Refer to the Streamed Audio Driver Defined Values page for the defined channels.
file | File descriptor.

Return Value

0 on success, PLAYERR_CHANNELBUSY on failure.

Code Example

/* Play WAV file on left channel 0 */
PlaybackWavFile( AUDIO_LEFT0, &wavFile );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Defined Data Structures

The following data structures are defined for use with the streamed audio driver

typedef struct wavfileinfo
{
   BYTE active;          /* File active? 0=no, 1=yes */
   FILE_DESCRIPTOR file; /* File pointer */
   BYTE channel;         /* Output channel, e.g. AUDIO_STEREO0 */
   BYTE looped;          /* 0 if not looped, 1 if looped. */
   ULONG fileLength;     /* Overall WAV file length (unused) */
   ULONG audioLength;    /* Audio data length (in bytes) */
   ULONG audioPos;       /* Current position in sample data */
   UWORD numChannels;    /* Num. channels: 1 = mono, 2 = stereo */
   ULONG sampleRate;     /* Sample rate, e.g. 32000 */
   UWORD bitsPerSample;  /* Bits per sample, e.g. 8, 16 etc */
   WORD initialBuffer[SECTOR_WORDS]; /* From initial 1 sector read */
   UWORD initialBufferUsed; /* Num bytes in initialBuffer */

   WORD format;          /* Format: 1=pcm, 6=A-Law, 7=U-Law */
} WAVFILEINFO;

Note: None of these variables should be changed as they are used/updated internally by the audio streaming driver. It may however be useful to read some of these values (e.g. sampleRate or bitsPerSample).

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Defined Values

Streamed Audio Driver Defined Values

The following values are defined for use with the streamed audio driver:

Streamed Audio Defined Audio Channels

Label | Meaning
AUDIO_LEFT0 | Left channel 0
AUDIO_RIGHT0 | Right channel 0
AUDIO_STEREO0 | Stereo channels 0
AUDIO_LEFT1 | Left channel 1
AUDIO_RIGHT1 | Right channel 1
AUDIO_STEREO1 | Stereo channels 1

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Format Considerations

The Streamed Audio Driver supports the following .wav file formats:

  • 16-bit uncompressed PCM
  • 8-bit uncompressed PCM
  • 8-bit Ulaw compressed PCM
  • 8-bit Alaw compressed PCM.

The driver will automatically recognise and play .wav files with any of the above formats
The choice of format to use is governed by a compromise between audio quality and performance.

Listing the above formats in order of sound quality (best first) 16-bit uncompressed › 8-bit ULaw compressed › 8-bit Alaw compressed › 8-bit uncompressed.

The list in order of loading/processing time required is the reverse of the above (fastest first) 8-bit uncompressed › 8-bit Ulaw or Alaw compressed › 16-bit uncompressed.

The following table compares all the formats relative to 16-bit uncompressed pcm:

 | File size | CF Load & Decompress Time | Quality
16 bit uncompressed | 1.0 | 1.0 | Best
8 bit Ulaw compressed | 0.5 | 0.67 |
8 bit Alaw compressed | 0.5 | 0.67 |
8 bit compressed | 0.5 | 0.5 | Worst

8-bit Ulaw compression gives the best compromise between performance and quality. This format gives significant savings in Compact Flash bandwidth requirements, which is valuable when streaming multiple audio channels (and possibly images as well).

Note:The difference in sound quality compared to 16 bit is not noticeable in most situations.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Sample Preparation

When preparing audio files to use with the Streamed Audio Driver please refer to the following guidelines:

Sample Size

Loading audio files from Compact Flash creates a processing overhead. The overhead can be minimised by adjusting the size of the audio sample. This is demonstrated in the following example:

Example

A video game application spins an animated reel, and at the same time plays an audio sample. The sample is a repeated sound that simulates a mechanical reel spinning. There are 2 possible approaches to playing the audio in this case:

  • The audio sample is prepared as a 500ms sample. The period that the reel spins for, and therefore the sample plays for, is 5 seconds. To play the sample for this time period the file must be loaded, and rewound to the start 10 times. This requires the initial Compact Flash access to load the file,and additional accesses every time the file is rewound.
  • This audio sample is prepared as a 5 second sample comprised of 10 copies of the 500ms sample. This single file will only need to be played once, and the overhead of rewinding the file is removed.

One of the advantages of working with compact flash as a storage medium is the increased amount of memory available to store sound samples. Audio samples can therefore be larger removing the need in some cases for rapid looping of small samples, and therefore reducing the processing load.

Silence/Fading

It is recommended that at the end of all audio samples either the sample is faded to silence, or a period of silence is added. Failure to do this may result in an audible click when a sample is stopped and immediately restarted. The audible click is a result of the following sequence of events:

  • Audio sample stopped. Audio amplifier is at an unknown voltage level.
  • Audio amplifier begins to settle to 0 volts (silence)
  • Sample restarts before the audio amplifier has settled causing the volatge to dip to 0 volts and rise rapidly causing a click.

By fading samples or adding silence the audio amplifier is forced to 0 volts before the sample ends. 5ms of silence should be sufficient to prevent this problem.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Sample Preparation

Streamed Audio Driver Recommended Usage

To achieve maximum reliability when using the Pluto 6 Streamed Audio Driver the following recommendations should be observed:

Sound Sample Preparation on Compact Flash

  1. Always use a single file format for sound files within a game. It is recommended that 16Khz U-law compressed files be used for maximum reliability.
  2. Always de-fragment the Compact Flash FAT32 file system before use on the Pluto 6. This can be done using the disk defragmenter program supplied with Microsoft ® Windows®.

Using Sound Samples on Pluto 6

  1. Initialise all sound file descriptors before playing any sound samples. If sound samples are playing they should be stopped before initialising any new samples.
  2. It is recommended that the function SearchForWavFile() is used for initialising sound files rather than the InitWavFile() function. If the SearchForWavFile() function is used to initialise the sound sample, the PlaybackWavFile() function should be used to play the sound.
  3. Do not attempt to access the Compact Flash card for other purposes, for example to load an image file, whilst a sound sample is playing.
  4. Do not attempt to play stereo samples on mono channels.
  5. Do not attempt to play mono samples on stereo channels.

Detailed Information

The above recommendations for usage are derived from the way in which the sound, ATA and FAT32 drivers on Pluto 6 have been implemented. This section provides a detailed description of how sound samples are played on Pluto 6.

Initialising the Sound Sample

Two functions are provided to initialise the sound sample to be played:

  • void InitWavFile( BYTE *filename, WAVFILEINFO *wavFileInfo )

    The InitWavFile() function calls the FileOpen() function in the FAT32 driver. A linked list of the disk clusters used by the file is saved in Pluto 6 memory, and a WAVFILEINFO structure is populated with information from the file header.

  • BYTE SearchForWavFile( BYTE *filename, FILE_DESCRIPTOR *file )

    The SearchForWavFile() function also calls the FileOpen() function in the FAT32 driver. A linked list of the disk clusters used by the file is saved in Pluto 6 memory, and a FILE_DESCRIPTOR pointer is saved to allow the file to be accessed.

The InitWavFile() function will typically store a large amount of data in the WAVFILEINFO structure for every file opened. Because of the amount of available memory for storing open file information it is not possible to have many files open at the same time.

The FILE_DESCRIPTOR used by the SearchForWavFile() function uses less memory that the WAVFILEINFO structure use in the InitWavFile(). It is therefore recommended that the SearchForWavFile() function is used in applications that require multiple files to be open.

It should also be noted that if the InitWavFile() function is used, and the associated WAVFILEINFO structure declared locally, this may result in stack overflow due to the amount of data contained in the structure. The smaller FILE_DESCRIPTOR used in the SearchForWavFile() function will take less stack space if declared locally.

Process access to the Compact Flash card is not scheduled or prioritised. If access requests to the Compact Flash card file system exceed the available processing time failures will occur. It is recommended that sound sample files are not initialised whilst open files are being played to avoid exceeding the available processing time. If available processing time is exceeded in this way, either files will not be opened correctly and will be inaccessible, or failure on the DMA channel used to send sound data to the audio amplifier will occur. Failures will also occur if image files are loaded whilst sound samples are being initialised or loaded.

If it is necessary to load new samples, to avoid exceeding available processing time, it is advisable to stop any sound samples that are playing using the StopAudioChannel() function. The SoundChannelBusy() function can be used to determine if a channel is in use and needs to be stopped as demonstrated in the code sample:

    while(SoundChannelBusy(channelnumber))
    {
        StopAudioChannel(channelnumber);
    }

It should also be noted that a linked list of clusters used by the opened sound file is stored in memory on the Pluto 6 board. If the file that has been opened is not fragmented, and the clusters are contiguous, the linked list will only contain the start and end clusters. To ensure the minimum memory usage when opening files it is highly recommended that files/file systems on the Compact Flash card are de-fragmented.

WAV File Format Usage

The sound driver supports a variety of .wav file formats. U-Law compressed files offer 2:1 compression ratio. The decompression of the sound data is done in real time with a relatively low processing overhead. Using U-Law compressed files does mean that the amount of data transferred from the Compact Flash card is reduced. The reduced Compact Flash access reduces the overall processing overhead involved with playing sound samples.

Audio Channels

The driver will allow developers to specify playing a stereo file over a mono channel. When the audio data is processed in an Interrupt Service the driver will detect that a stereo sample is being played over a mono channel and will change the channel status to CHANNEL_INVALIDCHANNEL.

If a mono sample is played over a stereo channel the sound will only be audible over the left channel, and the right channel will be silenced. Playing mono samples over stereo channels is not recommended because playback is restricted to the left channel only.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Heber Sound File Audio Driver

The Heber Sound File audio driver is an alternative streaming sound driver, which still provides the capability to stream up to 4 channels of audio from a Compact Flash card.

The new driver supports a proprietary Heber audio format, which has the following features:

  • The Heber Sound Files are pre-processed - header information has been reduced to a single length field.
  • The audio data is compressed using CCITT-ULAW.
  • The files are a multiple of 512 bytes in size, to ensure they do not cross sector boundaries on the Compact Flash card (this reduces file reading complexity within the FAT32 driver).
  • Stereo samples are stored in separate HSF files.

The reason for these characteristics is to reduce the complexity of the driver, and hence reduce CPU load/file accesses within interrupt routines. The simplicity of this driver will also increase reliability.

API Functions

The following API functions are associated with this module:

Function | Description
OpenHSFFile | This function prepares a HSF for playback using the function PlayHSFFile().
PlayHSFFile | This function plays back the specified HSF on the specified channel.
PlayStereoHSFFiles | This function plays back a pair of HSF which make up a stereo sample synchronously on the specified channel.
StopHSFChannel | This function stops the currently playing HSF file on the specified audio channel and rewinds the audio file.
SetHSFChannelVolume | This function sets the volume on a specified channel.
HSFChannelBusy | This function checks to see if an audio sample is currently playing on a specified channel.

See Also

  • HSF Audio Defined Values
  • HSF Audio Driver Recommended Usage
  • HSF Audio Configuration Data
  • HSF Audio Sample Preparation
  • HSF Audio Pre-Processing Utility
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Open Heber Sound File API Function

Heber Sound File Audio Driver

API Function

UBYTE OpenHSFFile(const UBYTE *filename, FILE_DESCRIPTOR *file)

Description

This function prepares a Heber Sound File for playback using the function PlayHSFFile().

Parameters

Parameter | Description
filename | .hsf file name on the Compact Flash Card.
file | Pointer to a FILE_DESCRIPTOR structure.

Return Value

Returns HSF_SUCCESS if successful.
Returns HSFERR_FILENOTFOUND if the file cannot be found in the current directory on the Compact Flash card.

Code Example

/* Prepare HSF file */
FILE_DESCRIPTOR HSFFile;

OpenHSFFile( “music.hsf”, &HSFFile );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Volume Heber Sound File API Function

Heber Sound File Audio Driver

API Function

UBYTE SetHSFChannelVolume(UBYTE channel, UBYTE volume)

Description

Sets the volume on the specified channel. The volume ranges from 0 (silent) to 255 (maximum). However there are only 16 discrete volumes (e.g. 0, 16, 32 , 224, 240).

Parameters

Parameter | Description
channel | Output audio channel. Refer to the HSF Audio Driver Defined Values page for the defined channels.
volume | Volume level.

Return Value

Returns HSF_SUCCESS if successful.
Returns PLAYERR_INVALIDCHANNEL if the specified channel is not one of the defined channels.

Code Example

/* set the volumes of channels left and right 0 */
SetHSFChannelVolume( AUDIO_LEFT0, (UBYTE)100 );
SetHSFChannelVolume( AUDIO_RIGHT0, (UBYTE)100 );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Play Heber Sound File API Function

Heber Sound File Audio Driver

API Function

UBYTE PlayHSFFile(UBYTE channel, FILE_DESCRIPTOR *file)

Description

This function plays back the specified Heber Sound File on the specified channel. The HSF must be opened using the function OpenHSFFile() before the PlayHSFFile() function is called. Note that a single Heber Sound File contains only mono audio data, if this function is called with a stereo channel argument e.g. AUDIO_STEREO0, the same data will be played on both of the corresponding left and right channels. To play differing left/right channel audio data of a stereo sample, use the function PlayStereoHSFFiles().

Parameters

Parameter | Description
channel | Output audio channel. Refer to the HSF Audio Driver Defined Values page for the defined channels.
file | File descriptor.

Return Value

Returns HSF_SUCCESS if successful.
Returns PLAYERR_CHANNELBUSY if the specified channel is busy.
Returns PLAYERR_INVALIDCHANNEL if the specified channel is not one of the defined channels.

Code Example

/* Play HSF on left channel 0 */
PlayHSFFile( AUDIO_LEFT0, &HSFFile );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Play Stereo Heber Sound File API Function

Heber Sound File Audio Driver

API Function

UBYTE PlayStereoHSFFiles(UBYTE channel, FILE_DESCRIPTOR *leftfile, FILE_DESCRIPTOR *rightfile)

Description

The left/right channel audio data is kept in seperate files by the Heber Sound File format. This function ensures synchronous playback on the specified channel of a specified Heber Sound File pair which make up a stereo sample. Both the HSFs must be opened using the function OpenHSFFile() before the PlayStereoHSFFile() function is called.

Parameters

Parameter | Description
channel | Output audio channel - must be AUDIO_STEREO0/1. Refer to the HSF Audio Driver Defined Values page for the defined channels.
leftfile | File descriptor for the HSF containing left channel data.
rightfile | File descriptor for the HSF containing right channel data.

Return Value

Returns HSF_SUCCESS if successful.
Returns PLAYERR_CHANNELBUSY if the specified channel is busy.
Returns PLAYERR_INVALIDCHANNEL if the specified channel is not one of the defined channels.

Code Example

/* Play stereo HSF pair on stereo channel 0 */
PlayStereoHSFFiles ( AUDIO_STEREO0, &HSFFile_left, &HSFFile_right );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stop Heber Sound File API Function

Heber Sound File Audio Driver

API Function

UBYTE StopHSFChannel(UBYTE channel)

Description

This function stops playback on the specified channel of the Heber Sound File currently playing on that channel. If a stereo channel is specified the corresponding left/right channels will be stopped. The Heber Sound File is rewound but not closed, and play back can be restarted with the PlayHSFile() or PlayStereoHSFiles() functions.

Parameters

Parameter | Description
channel | Output audio channel. Refer to the HSF Audio Driver Defined Values page for the defined channels.

Return Value

Returns HSF_SUCCESS if successful.
Returns PLAYERR_INVALIDCHANNEL if the specified channel is not one of the defined channels.

Code Example

/* Stop HSF playback on channel right 1 */
StopHSFChannel( AUDIO_RIGHT1 );

/* Stop stereo HSF pair or single file on stereo channel 0 */
StopHSFChannel( AUDIO_STEREO0 );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Check Heber Sound File Channel Busy API Function

Heber Sound File Audio Driver

API Function

UBYTE HSFChannelBusy(UBYTE channel)

Description

This function returns the status of the specified channel.

Parameters

Parameter | Description
channel | Output audio channel. Refer to the HSF Audio Driver Defined Values page for the defined channels.

Return Value

Returns HSF_SUCCESS if channel is not busy.
Returns PLAYERR_CHANNELBUSY if the specified channel is busy.
Returns PLAYERR_INVALIDCHANNEL if the specified channel is not one of the defined channels.

Code Example

/* check status of channel right 0 */
if(HSFChannelBusy(AUDIO_RIGHT0)
{
    /* channel is busy - now stop the channel */
    StopHSFChannel(AUDIO_RIGHT0);
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HSF Audio Defined Values

HSF Audio Driver Defined Values

The following values are defined for use with the Heber Sound File audio driver:

HSF Audio Defined Audio Channels

Label | Meaning
AUDIO_LEFT0 | Left channel 0
AUDIO_RIGHT0 | Right channel 0
AUDIO_STEREO0 | Stereo channels 0
AUDIO_LEFT1 | Left channel 1
AUDIO_RIGHT1 | Right channel 1
AUDIO_STEREO1 | Stereo channels 1

HSF Audio Defined Error Return Codes

Label | Meaning
HSFERR_FILENOTFOUND | The file name argument passed to the OpenHSFFile function was not found.
HSFERR_CHANNELBUSY | The channel argument passed to one of the PlayHSF functions is busy, e.g. AUDIO_STEREO0 was passed while a sample is already playing on AUDIO_LEFT0 or AUDIO_RIGHT0.
HSFERR_INVALIDCHANNEL | The channel argument passed to any HSF API function which requires a channel to be specified was not one from the the above table.

HSF Audio Defined Success Return Codes

Label | Meaning
HSF_SUCCESS | The function has returned successfully.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HSF Audio Recommended Usage

HSF Audio Driver Recommended Usage

To achieve maximum reliability when using the Pluto 6 HSF Audio Driver the following recommendations should be observed:

Sound Sample Preparation on Compact Flash

  1. Always de-fragment the Compact Flash FAT32 file system before use on the Pluto 6. This can be done using the disk defragmenter program supplied with Microsoft® Windows®.

Using Sound Samples on Pluto 6

  1. Initialise all sound file descriptors before playing any sound samples. If sound samples are playing they should be stopped before initialising any new samples.
  2. Do not attempt to access the Compact Flash card for other purposes, for example to load an image file, whilst a sound sample is playing.

Initialising the Sound Sample

Process access to the Compact Flash card is not scheduled or prioritised. If access requests to the Compact Flash card file system exceed the available processing time failures will occur. It is recommended that sound sample files are not initialised whilst open files are being played to avoid exceeding the available processing time. If available processing time is exceeded in this way, either files will not be opened correctly and will be inaccessible, or failure on the DMA channel used to send sound data to the audio amplifier will occur. Failures will also occur if image files are loaded whilst sound samples are being initialised or loaded.

If it is necessary to load new samples, to avoid exceeding available processing time, it is advisable to stop any sound samples that are playing using the StopHSFChannel() function. The HSFChannelBusy() function can be used to determine if a channel is in use and needs to be stopped as demonstrated in the code sample:

/* check status of channel right 0 */
if(HSFChannelBusy(AUDIO_RIGHT0)
{
        /* channel is busy - now stop the channel */
        StopHSFChannel(AUDIO_RIGHT0);
}

while(HSFChannelBusy(channel))
        {
        // Wait for channel to finish
        }

It should also be noted that a linked list of clusters used by the opened sound file is stored in memory on the Pluto 6 board. If the file that has been opened is not fragmented, and the clusters are contiguous, the linked list will only contain the start and end clusters. To ensure the minimum memory usage when opening files it is highly recommended that files/file systems on the Compact Flash card are de-fragmented.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Using the HSF Audio Driver in projects

In order to use the HSF driver in a project/game, some editing of the project files at game level is required.

Config.c

Add the following to the list of header file includes at the top of the file:

#include	"interface.h"

Then add a configuration structure instance for the driver at the bottom of the file:

/* storage driver to use with HSF audio driver */
const AUDIOHSFCFG AudioHSFCfg=
{
    &ATADevice,
};

Devices.c

Add the following to the list of header file includes at the top of the file:

#include	"interface.h"

Then add the following to the list of devices in the DeviceList[] structure array:

{&AudioHSFDevice,0,0,0},

Game.c/Demo.c

Remove the following call to initialise the old sound driver in the game code, otherwise multiple interrupt service routines will be installed to do similar things and neither driver will work:

InitStreamedAudio( &ATADevice );

The interrupt routines for the new HSF driver are installed using the device installer mechanism which handles all the other devices in the libraries.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Streamed Audio Sample Preparation

In order to create .hsf files to use with the HSF audio driver, use the HSF Pre-Processing utility. When preparing audio files to convert with this utility and use with the HSF Audio Driver please refer to the following guidelines:

Sample Size

Loading audio files from Compact Flash creates a processing overhead. The overhead can be minimised by adjusting the size of the audio sample. This is demonstrated in the following example:

Example

A video game application spins an animated reel, and at the same time plays an audio sample. The sample is a repeated sound that simulates a mechanical reel spinning. There are 2 possible approaches to playing the audio in this case:

  • The audio sample is prepared as a 500ms sample. The period that the reel spins for, and therefore the sample plays for, is 5 seconds. To play the sample for this time period the file must be loaded, and rewound to the start 10 times. This requires the initial Compact Flash access to load the file, and additional accesses every time the file is rewound.
  • This audio sample is prepared as a 5 second sample comprised of 10 copies of the 500ms sample. This single file will only need to be played once, and the overhead of rewinding the file is removed.

One of the advantages of working with compact flash as a storage medium is the increased amount of memory available to store sound samples. Audio samples can therefore be larger removing the need in some cases for rapid looping of small samples, and therefore reducing the processing load.

Silence/Fading

It is recommended that at the end of all audio samples either the sample is faded to silence, or a period of silence is added. Failure to do this may result in an audible click when a sample is stopped and immediately restarted. The audible click is a result of the following sequence of events:

  • Audio sample stopped. Audio amplifier is at an unknown voltage level.
  • Audio amplifier begins to settle to 0 volts (silence)
  • Sample restarts before the audio amplifier has settled causing the volatge to dip to 0 volts and rise rapidly causing a click.

By fading samples or adding silence the audio amplifier is forced to 0 volts before the sample ends. 5ms of silence should be sufficient to prevent this problem.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HSF Pre-Processing Utility

Heber Sound File (HSF) Pre-processing Utility

Background

The Pluto 6 streaming audio driver is able to play various WAV formats - differing codecs, samplerates, bitrates etc. An alternative driver, the Heber Sound File Audio Driver has been written to support a single .hsf audio format - Heber Sound Files. This driver has been produced as it offers reduced complexity, which in turn reduces CPU loading and increases reliability.

Heber Sound Files need to be pre-processed before they can be used. This pre-processing utility can be used to convert WAV files to HSF format. Before files can be processed using this utility they need to be in the following WAV format:

  • CCITT-ULAW compressed audio data format.
  • 32Khz sample rate.
  • 8 bits per sample.
  • Stereo or mono channels.

There are numerous shareware utilities available which will convert WAVs and other file types (e.g. MP3s) to this particular WAV format, but usually only if the source file uses 16 bits per sample or higher.

Usage

To convert a WAV file to .hsf format open a DOS window and type one of the following commands:

ulawconv [drive:][path]inputfile.wav | Converts inputfile.wav to inputfile.hsf if the input file contains mono audio data. Converts inputfile.wav to inputfile_l.hsf containing left data and inputfile_r.hsf containing right data if the input file contains stereo audio data.
ulawconv [/?] | Displays the help information for the tool.

Examples

  1. Convert mono_ulaw.wav:

    ulawconv mono_ulaw.wav

    If the WAV file is in the correct format as above, the following output is generated:

    File information:
    Compression Code: ULAW
    Channels: MONO
    Sample Rate: 32000Hz

    and the file mono_ulaw.hsf is created in the current directory.

  2. Convert mono_ulaw.wav:

    ulawconv stereo_ulaw.wav

    If the WAV file is in the correct format as above, the following output is generated:

    File information:
    Compression Code: ULAW
    Channels: STEREO
    Sample Rate: 32000Hz

    and the files stereo_ulaw_l.hsf and stereo_ulaw_r.hsf are created in the current directory.

  3. Convert mono_pcm.wav:

    ulawconv mono_pcm.wav

    If the WAV file is in the wrong format (not ULAW data), the following output is generated:

    File information:
    Compression Code: PCM
    Channels: MONO
    Sample Rate: 32000Hz

    This file type is not supported and no files are created.

  4. Display the help information:

    ulawconv

    This will display the help information in the DOS window.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


MS WIndows BMP Files

Microsoft® Windows® BMP Graphics File Loader

Microsoft® Windows® BMP is a bitmap graphics file format that supports 24 bit per pixel colour. This file loader allows developers to load .bmp graphics files from a Compact Flash card to video memory with real time conversion from 24 bit to 16 bit colour.

API Functions

The following API functions are associated with this module:

Function | Description
LoadMsWinBmp24 | This function loads a 24 bit per pixel Microsoft® Windows® BMP image into video memory.
EnableAlphaBlending | Enables BMP images to be loaded with Alpha Blending characteristics.
DisableAlphaBlending | BMP images loaded normally.
StatusAlphaBlending | Returns the status of loading.

See Also

  • Microsoft Windows® BMP Defined Data Structures
  • File Loader Error Codes
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load MS Windows BMP API Function

Microsoft® Windows® BMP Graphics File Loader

API Function

UBYTE LoadMsWinBmp24(const DEVICE* dev, BYTE *filename, BMPFILEINFO *bmpinfo, UWORD *memptrdatain, ULONG dataoutaddress)

Description

This function loads a 24 bit per pixel Microsoft® Windows® BMP image into video memory. The data is initially loaded into a temporary memory buffer and then copied to an output location in video memory allowing the data to be reversed. This is necessary because data in bitmaps is stored in reverse order.

Note: Sprites loaded from Compact Flash must have a width that is a multiple of 8 pixels.

Parameters

Parameter | Description
dev | Address of the device.
filename | Pointer to the name of the file to load.
bmpinfo | Pointer to BMP file information structure.
memptrdatain | Pointer to temporary memory areas.
dataoutaddress | Output memory address.

Return Value

Returns 0 on success.
Returns error code on failure.

Code Example

/* declare a BMP file info structure */
BMPFILEINFO bmpinfopluto6;

/*
set the memory address in video memory for the
temporary data buffer
*/
(ULONG)meminptr = (ULONG)0x31c00000;

/*
set the memory address in video memory to hold the
final image data
*/
(ULONG)memoutptr = (ULONG)0x30400000;

/* load a bmp bitmap file called 'pluto6.bmp' from an ATA device */
LoadMsWinBmp24(&ATADevice, "pluto6.bmp", &bmpinfopluto6,
meminptr, memoutptr);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Enable Alpha Blending Loading API Function

Microsoft® Windows® BMP Graphics File Loader

API Function

void EnableAlphaBlendingLoading()

Description

Enable BMP images to be loaded with Alpha Blending bit set. The Image loaded after this will load with the Alpha bit set.

Parameters

None.

Return Value

None.

Code Example

If(!StatusAlphaBlendingLoading ())

{

EnableAlphaBlendingLoading();

}

squaresbmp_alpha.start_address = offscreen;

            /*          load bitmap into memory and return number of

                        bytes loaded in video memory */

offscreen += loadwindowsbmp(&SerialDevice,0,"squares.bmp", &squaresbmp_alpha.bmpinfo, offscreen);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Disable Alpha Blending Loading API Function

Microsoft® Windows® BMP Graphics File Loader

API Function

void DisableAlphaBlendingLoading()

Description

Enables BMP images to be loaded without the Alpha blending bit set.

Parameters

None.

Return Value

None.

Code Example

If(!StatusAlphaBlendingLoading ())

{

EnableAlphaBlendingLoading();

}

squaresbmp_alpha.start_address = offscreen;

            /*          load bitmap into memory and return number of

                        bytes loaded in video memory */

offscreen += loadwindowsbmp(&SerialDevice,0,"squares.bmp", &squaresbmp_alpha.bmpinfo, offscreen);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Status Alpha Blending Loading API Function

Microsoft® Windows® BMP Graphics File Loader

API Function

UBYTE StatusAlphaBlendingLoading()

Description

Returns the status of loading.

Parameters

None.

Return Value

Returns TRUE if image is loaded with Alpha Blending bit set.
Returns FALSE if image is loaded with Alpha blending bit cleared.

Code Example

If(!StatusAlphaBlendingLoading ())

{

EnableAlphaBlendingLoading();

}

squaresbmp_alpha.start_address = offscreen;

            /*          load bitmap into memory and return number of

                        bytes loaded in video memory */

offscreen += loadwindowsbmp(&SerialDevice,0,"squares.bmp", &squaresbmp_alpha.bmpinfo, offscreen);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


MS Windows BMP File Loader Structures

Microsoft® Windows® BMP File Loader Defined Data Structures

The following data structure is used to hold the height and width data for a Microsoft® Windows® BMP format image:

/* BMP File Information */
typedef struct
{
    ULONG	imagewidth;		/* height in pixels */
    ULONG	imageheight;		/* width in pixels  */
} BMPFILEINFO;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


TGA File Loader

TGA Graphics File Loader

TGA is a bitmap graphics file format that supports 16 bit per pixel colour. This file loader allows developers to load .tga graphics files from a Compact Flash card to video memory without the need for real time conversion from 24 bit to 16 bit colour.

API Functions

The following API functions are associated with this module:

Function | Description
LoadTGA16 | This function loads a TGA 16 bit per pixel image into video memory.

See Also

  • TGA Defined Data Structures
  • File Loader Error Codes
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load TGA API Function

TGA Graphics File Loader

API Function

UBYTE LoadTGA16(const DEVICE* dev, BYTE *filename, TGAFILEINFO *tgainfo, UWORD *memptrdatain, ULONG dataoutaddress)

Description

This function loads a TGA 16 bit per pixel image into video memory. The data is initially loaded into a temporary memory buffer and then copied to an output location in video memory allowing the data to be reversed. This is necessary because data in bitmaps is stored in reverse order.

Parameters

Parameter | Description
dev | Address of the device.
filename | Pointer to the name of the file to load.
tgainfo | Pointer to TGA file information structure.
memptrdatain | Pointer to temporary memory areas.
dataoutaddress | Output memory address.

Return Value

Returns 0 on success.
Returns error code on failure.

Code Example

/* declare a TGA file info structure */
TGAFILEINFO tgainfopluto6;

/*
set the memory address in video memory for the
temporary data buffer
*/
(ULONG)meminptr = (ULONG)0x31c00000;

/*
set the memory address in video memory to hold the
final image data
*/
(ULONG)memoutptr = (ULONG)0x30400000;

/* load a tga bitmap file called 'pluto6.tga' from an ATA device */
LoadTGA16(&ATADevice, "pluto6.tga", &tgainfopluto6,
meminptr, memoutptr);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


TGA File Loader Data Structures

TGA File Loader Defined Data Structures

The following data structure is used to hold the height and width data for a TGA format image:

/* TGA File Information */
typedef struct
{
    ULONG	imagewidth;		/* height in pixels */
    ULONG	imageheight;		/* width in pixels  */
} TGAFILEINFO;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Heber Image File Loader

Heber Image File Graphics File Loader

HIF (Heber Image File) is a proprietary image format. HIF files are created using an image pre-processing tool from a 24 bit per pixel Microsoft® Windows® BMP bitmap file. Pre-processing allows the image data to be reversed and converted from 24 to 16 bit colour prior to use. This offers a significant performance increase when loading files because they can be loaded directly into video memory.

API Functions

The following API functions are associated with this module:

Function | Description
LoadHIF | This function loads a 16 bit per pixel Heber Image File image into video memory.

See Also

  • HIF Defined Data Structures
  • File Loader Error Codes
  • bmp24tohif Bitmap to HIF file conversion tool
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load HIF API Function

Heber Image File Graphics File Loader

API Function

UBYTE LoadHIF(const DEVICE* dev, BYTE *filename, HEBERIMAGEINFO *heberinfo, UWORD *dataoutaddress)

Description

This function loads a 16 bit per pixel Heber Image File image into video memory.

Note: Sprites loaded from Compact Flash must have a width that is a multiple of 8 pixels.

Remarks

For more information on conversion of .bmp bitmap files to .hif Heber Image File files see the bmp24tohif conversion tool page.
The image address for use in displaying images is 8 bytes.

Parameters

Parameter | Description
dev | Address of the device.
filename | Pointer to the name of the file to load.
heberinfo | Pointer to HIF file information structure.
dataoutaddress | Output memory address.

Return Value

Returns 0 on success.
Returns error code on failure.

Code Example

/* declare a HIF file info structure */
HEBERIMAGEINFO hbrimage;

/*
set the memory address in video memory to hold the
final image data
*/
(ULONG)memoutptr = (ULONG)0x31c00000;

/* load a hif file called 'pluto6.hif' from an ATA device */
LoadHIF(&ATADevice, "pluto6.hif", &hbrimage, memoutptr );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HIF Loader Data Structures

Heber Image File Loader Defined Data Structures

The following data structure is used to hold the height and width data for a Heber Image File image:

/* HIF File Information */
typedef struct
{
    ULONG	imageheight;		/* height in pixels */
    ULONG	imagewidth;		/* width in pixels  */
    ULONG	imagedataaddress;	/* address of image */
} HEBERIMAGEINFO;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Graphics File Loader Error Codes

The following error codes are common to all of the graphics file loaders and are used when a file fails to load:

Error Code | Description
FILENOTFOUNDERR | The file requested can not be found on the storage media.
FILEFORMATERR | The file requested is not in the correct format to be loaded by the function.
FILECOMPRESSEDERR | The file requested is compressed and therefore can not be loaded.
UNEXPECTEDERR | An unexpected error occurred during the file loading process.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Tools and Utilities

The Pluto 6 control board is supplied with a set of software tools and utilities to enable developers to pre-process data for use with the software library drivers. The following sets of tools and utilities are supplied:

Image and Font Tools

Advanced Video Driver Image Processing Utilities

The image processing utilities allow the conversion of image files, for example .bmp and .jpg images, into a format that is required for some of the API functions in the Advanced Video Driver. The ultilities are designed to run under Windows® 2000/XP operating systems from the command line.

Advanced Video Driver Font Processing Utilities

The font processing utilities allow the conversion of font files into a format that is required for some of the API functions in the Advanced Video drivers. The ultilities are designed to run under Windows® 2000/XP operating systems from the command line.

Heber Image Format (HIF) Pre-processing Tool

The Heber Image Format (HIF) pre-processing tool converts 24 bit .bmp bitmap images to 16 bit data and reverse the data order allowing the images to be loaded with less real time processing. The tool is designed to run under Windows® 2000/XP operating systems from the command line.

Heber Sound File (HSF) Pre-processing Tool

The Heber Sounde File (HSF) pre-processing tool converts WAV files with 32Khz, 8 bit, CCITT-ULAW encoded audio data into a file which is a multiple of 512 bytes long containing a single length (in sectors) field and the ULAW encoded data. The tool is designed to run under Windows® 2000/XP operating systems from the command line.

Build Tools

Project Building Tools

The building tools are supplied to help with such tasks as updating project files and dependencies.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Advanced Video Driver Image Conversion Utilities

A set of utilities are provided to pre-process image files for the Advanced Video Driver.

Utilities

Utility | Description
imagconv8.bat | Used for pre-processing 8-bit images (generates optimum palette palette.c).
imagconv8std.bat | Used for pre-processing 8-bit images (uses standard VGA palette stdpalette.c).
imagconv16.bat | Used for pre-processing 16-bit images.

The pre-processed files can be used with the following video functions:

API Function | Description
CalypsoLoadImage() | Load an image from system to video memory.
CalypsoLoadImageLayer() | Load an image from system memory to a defined layer video memory.
CalypsoLoadImageConvert8to16() | Load an image from system memory to video memory with 8-bit to 16-bit colour conversion.
CalypsoLoadImageLayerConvert8to16 () | Load an image from system memory to a Display Layer in video memory with 8-bit to 16-bit colour conversion.
CalypsoLoadSprite() | Load image from system to video memory and create an image mask in video memory following the image in video memory.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


8 Bit Image Conversion Utility

8 Bit Image Conversion Utility (imagconv8.bat)

This utility will convert 24 bit .bmp or .jpg image files to 8 bit colour files and create an optimised 8 bit palette for the image files. The converted image files and associated palette can be used in game projects.

Using the Utility

  1. Create a directory called source in your project directory
  2. Copy all of the image files that you wish to convert into the the source directory that you have created
  3. Open a DOS window and change directory to your project directory
  4. Type imagconv8 big and press enter
  5. This will create .c files in the project directory from the image files in the source directory with big endian data encoding and an optimised palette file palette.c for the image files.

    Each .c file will contain the image data in the following structure:

    const CALYPSOIMAGE image_name =
{
    image parameters...
    palette data...
    bit map data...
};

    The type CALYPSOIMAGE is defined as:

    typedef struct calypsoimage
{
    ULONG size_bytes;           /* image size bytes */
    WORD color8;                /* 1=8bit 0=16bit */
    WORD palette_size;          /* number of palette entries */
    WORD width;                 /* width in pixels */
    WORD height;                /* height in lines */
    const PALETTE_RGB *palette; /* palette data */
    const WORD *data;           /* image data */
} CALYPSOIMAGE;
  6. Create .h header files for the images and palette that have been created for the project.

Example

  • Image files image1.bmp and image2.bmp 24 bit colour 800x600 background images
  • Put the image files into a a directory called source, e.g. C:\heber\pluto6\projects\my_game\source
  • From the project directory, e.g. C:\heber\pluto6\projects\my_game\ run the imagconv8 command
  • The following files will be created: image1.c, image2.c, palette.c
  • Using an editor create a header file in the project directory called images.h and enter the following information:
        extern const CALYPSOIMAGE image1;
    extern const CALYPSOIMAGE image2;
  • Save the file. This header file provides constant external declarations of data contained in the image1.c and image2.c files which can be referenced in the game code.
  • Using an editor create a header file in the project directory called palettes.h and enter the following information:
        extern const PALETTE_RGB palette[];
  • Save the file. This header file provides constant external declarations of data contained in the palette.c file which can be referenced in the game code.
  • In the makefile object list add image1.o, image2.oand palette.o to the list of objects to be built, e.g.
        ......
    oc		= m68k-coff-objcopy
    objects = game.o config.o devices.o demo.o custom.o  \
    sysram.o idram.o fpga.o image1.o image2.o palette.o
    ......
  • To reference the images in the game code include the images.h and palettes.h header files in the game files
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


8 Bit Image Conversion Utility (standard palette)

8 Bit Image Conversion Utility using the Standard Palette (imagconv8std.bat)

This utility will convert 24 bit .bmp or .jpg image files to 8 bit colour files using the standard palette for the image files. The converted image files and associated palette can be used in game projects.

Using the Utility

  1. Create a directory called source in your project directory
  2. Copy all of the image files that you wish to convert into the source directory that you have created
  3. Ensure that the file standard.pal is in your project directory
  4. Open a DOS window and change directory to your project directory
  5. Type imagconv8std big and press enter
  6. This will create .c files in the project directory from the image files in the source directory with big endian data encoding and a standard palette file stdpalette.c.

    Each .c file will contain the image data in the following structure:

    const CALYPSOIMAGE image_name =
{
    image parameters...
    palette data...
    bit map data...
};

    The type CALYPSOIMAGE is defined as:

    typedef struct calypsoimage
{
    ULONG size_bytes;           /* image size bytes */
    WORD color8;                /* 1=8bit 0=16bit */
    WORD palette_size;          /* number of palette entries */
    WORD width;                 /* width in pixels */
    WORD height;                /* height in lines */
    const PALETTE_RGB *palette; /* palette data */
    const WORD *data;           /* image data */
} CALYPSOIMAGE;
  7. Create .h header files for the images and palette that have been created for the project.

Example

  • Image files image1.bmp and image2.bmp 24 bit colour 800x600 background images
  • Put the image files into a a directory called source, e.g. C:\heber\pluto6\projects\my_game\source
  • Ensure that the standard palette standard.pal is present in the project directory
  • From the project directory, e.g. C:\heber\pluto6\projects\my_game\ run the imagconv8std command
  • The following files will be created: image1.c, image2.c, stdpalette.c
  • Using an editor create a header file in the project directory called images.h and enter the following information:
        extern const CALYPSOIMAGE image1;
    extern const CALYPSOIMAGE image2;
  • Save the file. This header file provides constant external declarations of data contained in the image1.c and image2.c files which can be referenced in the game code.
  • Using an editor create a header file in the project directory called palettes.h and enter the following information:
        extern const PALETTE_RGB stdpalette[];
  • Save the file. This header file provides constant external declarations of data contained in the palette.c file which can be referenced in the game code.
  • In the makefile object list add image1.o, image2.oand stdpalette.o to the list of objects to be built, e.g.
        ......
    oc		= m68k-coff-objcopy
    objects = game.o config.o devices.o demo.o custom.o  \
    sysram.o idram.o fpga.o image1.o image2.o stdpalette.o
    ......
  • To reference the images in the game code include the images.h and palettes.h header files in the game files
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


16 Bit Image Conversion Utility

16 Bit Image Conversion Utility (imagconv16.bat)

This utility will convert 24 bit .bmp or .jpg image files to 16 bit colour files that can be included in game projects.

Using the Utility

  1. Create a directory called source in your project directory.
  2. Copy all of the image files that you wish to convert into the the source directory that you have created.
  3. Open a DOS window and change directory to your project directory.
  4. Type imagconv16 big and press enter.
  5. This will create .c (advanced video driver) files in the project directory from the image files in the source directory with big endian data encoding as well as .bin file (for Compact Flash - old video driver).

    Each .c file will contain the image data in the following structure:

    const CALYPSOIMAGE image_name =
{
    image parameters...
    palette data...
    bit map data...
};

    The type CALYPSOIMAGE is defined as:

    typedef struct calypsoimage
{
    ULONG size_bytes;           /* image size bytes */
    WORD color8;                /* 1=8bit 0=16bit */
    WORD palette_size;          /* number of palette entries */
    WORD width;                 /* width in pixels */
    WORD height;                /* height in lines */
    const PALETTE_RGB *palette; /* palette data */
    const WORD *data;           /* image data */
} CALYPSOIMAGE;
  6. Create a .h header file for the images that have been created for the project.

Example

  • Image files image1.bmp and image2.bmp 24 bit colour 800x600 background images
  • Put the image files into a a directory called source, e.g. C:\heber\pluto6\projects\my_game\source
  • From the project directory, e.g. C:\heber\pluto6\projects\my_game\ run the imagconv16 command
  • The following files will be created: image1.c, image2.c
  • Using an editor create a header file in the project directory called images.h and enter the following information:
        extern const CALYPSOIMAGE image1;
    extern const CALYPSOIMAGE image2;
  • Save the file. This header file provides constant external declarations of data contained in the image1.c and image2.c files which can be referenced in the game code.
  • In the makefile object list add image1.o and image2.o to the list of objects to be built, e.g.
        ......
    oc		= m68k-coff-objcopy
    objects = game.o config.o devices.o demo.o custom.o  \
    sysram.o idram.o fpga.o image1.o image2.o
    ......
  • To reference the images in the game code include the images.h header file in the game files
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Advanced Video Driver Font Conversion Utilities

A set of utilities are provided to pre-process font files for the Advanced Video Driver.

Utilities

Utility | Description
fontconv.bat | Used for pre-processing font files for use with the Advanced Video Driver.

The Advanced Video Driver loads characters as required from pre-processed font files that are held in system memory. The following functions require a pre-processed font file to be built into the game code:

API Function | Description
CalypsoSetAsciiFont() | Set the current ASCII text font.
CalypsoSetUnicodeFont() | Assign Unicode font to code page.
CalypsoGetUnicodeFont() | Returns the Unicode Font assigned to Unicode code page.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Advanced Video Driver Font Conversion Utility (standard palette)

Advanced Video Driver Font Conversion Utility (fontconv.bat)

This utility will convert .ttf true type font files into .c files. The converted font files can be used in game projects.

Using the Utility

  1. Copy the font file that you wish to convert into the your project directory
  2. Open a DOS window and change directory to your project directory
  3. The conversion utilites requires the following parameters:
    filename | - without file extension
    size | - point size of the font
    unicode page
    - for example: 0 - unicode range 0x0000 - 0x007f
    80 - unicode range 0x0080 - 0x00ff
    400 - unicode range 0x0400 - 0x047f
    To convert the font file type fontconv <filename> <size> <unicode page> and press enter

    Example

    To convert the font file comic.ttf at 32 point size type:
    fontconv comic 32 0
    This will create a file called comic32_0.c which can be used in a game project.

Notes:

The Calypso 32 video processor will only support font sizes up to a maximum of 32 points.

This utility will only accept filenames in a DOS 8.3 format. The initial TTF file must only have 6 characters, so when combined with the point size, it does not create a filename greater than 8 characters before the .BDF extension.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


HIF Tool

Heber Image File (HIF) Pre-processing Utility

Background

Loading bitmap files from Compact Flash to video memory requires the following operations:

  • Convert the image data from 24 to 16 bit. This is required because the Calypso 32 video processsor will work to a maximum colour depth of 16 bits per pixel which is not a standard bitmap colour depth.
  • Reverse the image data. Bitmap data is stored in reverse (where the top left pixel data is at the end of the file). The image data is reversed when the file is loaded into video memory.

Performing the two operations above in real time presents a considerable overhead when loading files. To reduce the file load time it is possible to pre-process the image files to perform the colour depth conversion and data reversal.

bmp24tohif Pre-processing Tool

The bmp24tohif tool allows the game developer to pre-process 24 bit .bmp files. The tool outputs files in a proprietary Heber image file (.hif). .hif files can be copied on to a Compact Flash card and loaded within a game application running on a Pluto 6 controller using the LoadHIF() API function. Once .hif files have been loaded into video memory they can be used with the Video and Advanced Video API functions.

Usage

To convert an image to .hif format open a DOS window and type one of the following commands:

bmp24tohif [drive:][path]inputfile.bmp | Converts inputfile.bmp to inputfile.hif Note: If no output file name is specified the input file name is used with the .hif extension
bmp24tohif [drive:][path]inputfile.bmp [[drive:][path]outputfile.hif] | Converts inputfile.bmp to outputfile.hif
bmp24tohif [/?] | Displays the help information for the tool
bmp24tohif [/a] Infile Subfile | Set the Alpha bit in output file.

Examples

  1. Convert image1.bmp. The input file is in the current directory.

    bmp24tohif image1.bmp

    This will create output file image1.hif in the current directory.

  2. Convert image2.bmp. The input file is in the directory C:\images\

    bmp24tohif C:\images\image2.bmp C:\images\image3.hif

    This will create output file image3.hif in the directory c:\images\

  3. Execute a hif file with the alpha bit set.

    bmp24tohif /a

  4. Display the help information.

    bmp24tohif /?

    This will display the help information in the DOS window.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Build Tools

The following tools are provided with the Pluto 6 Development Kit to help with building software projects.

Tools

Utility Description
touch When user installs a new issue of a software library, it is strongly recommended that this tool is run before a project is rebuilt. This utility will update the timestamp on files and force the compiler to recreate all object files in the project folder. The dependencies to software librarieswill also be recreated.

Example of use:

At the command prompt in the project directory type touch *.c. Type make to rebuild the project and all of the objects will be rebuilt and dependencies updated.
makemap After making a project, you can visualise how the linker is storing data and functions into the memory (mapping of the memory) with the file link.map in the project folder. When using a P&E® debugger for debugging purposes, this utility converts the GNU format map file into a format that can be read by the P&E® software.

Example of use:

At the command prompt in the project directory type MAKEMAP modname. (Where modname is the s.19 file name without the file extension).
The map file will be loaded automatically at the same time as the .s19 file in the P&E® debugger.
dep This tool is used to manually re-generate the dependency file with the correct library paths.

Example of use:

At the command prompt in the project directory type dep fpga. This will re-generate the dependencies for the file fpga.c in the game project.
loc This tool is used to manually generate a static prototype file from a ‘C’ source file.

Example of use:

At the command prompt in the project directory type loc sysram. This will generate the static prototypes for the file sysram.c in the game project.
pro This tool is used to manually generate a prototype file from a ‘C’ source file.

Example of use:

At the command prompt in the project directory type pro devices. This will generate the prototypes for the file devices.c in the game project.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


See Also Topics

The following links provide further information:

  • Third Party Documentation
  • GNU Compiler
  • Software Conventions
  • Software Architecture
  • Source File Types
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Third Party Documents

Third Party Documentation

The following third party data sheets and technical manuals which are installed as part of the Pluto 6 Develoment Kit provide hardware device specific information for developers

  • Motorola 5206e ColdFire® User Manual
  • Motorola 5206e ColdFire® Programmers Reference Manual
  • Motorola 5206e ColdFire® Errata
  • Fujitsu Cremson MB86290A Graphics Controller Hardware Specification
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


GNU Compiler

The Pluto 6 control board is supplied with a build of the GNC C compiler for the Motorola ColdFire® 5206e, and all of the associated tools required to build and link software for the Pluto 6 control board. The compiler and tools are installed as part of the development CD-ROM.

Compilation and Linking

The make utility is used to invoke the GNU C compiler and linker to create a binary file that can be downloaded and executed on the Pluto 6 control board. The Pluto 6 software modules that are supplied with source code have an associated make file to allow the modules to be built. The following modules are supplied with make files:

  • Custom Peripherals Module This make file allows game developers to write their own custom device drivers and build a library archive file that can be included in games projects.
  • Application Module This make file allows game developers to build game projects including the drivers contained in the archive libraries for the other software modules.

Make Files

All make files are named ‘makefile’ (no file extension) and specify which files make up the project or library and how they are to be processed in order to produce the final executable file. Lines beginning with ‘#’ are comments.

The make file for a particular project or library is located in the same directory as the source code for that project or library. The makefiles supplied with the Pluto 6 software contain the following:

Variables

A make file variable associates a single label with a string of characters. This label may then be used in several places in the make file and will be replaced by the string when it is encountered by make. The syntax used to define a make file variable is as follows:

path= c:/MyProject/SourceFiles/

To use the value of the label in a command or dependency the following syntax is used:

gcc $(path)FileName.c

Note: the GNU compiler gcc uses UNIX style forward slashes in its path names.

The following variable declarations are used in the Pluto 6 make files:

Variable | Use | Example
target The name of the target platform the files are to be built for. It is also the name of the subdirectory, which contains the library archive for this platform. #build for pluto 6
target=pluto6
script The name of the linker script file to be used. #link to run from dram
script=lnkdram.x
target The name of the final output file that will be produced (without a file extension). #output file called demo
output=demo
lhdw The path to the header files, object files, and hardware library archive file. #path the hardware module
lhdw=../../libs/hardware/$(target)
lper The path to the header files, object files, and peripherals library archive file. #path the peripherals module
lper=../../libs/peripherals/$(target)
lcper The path to the header files, object files, and custom peripherals library archive file. #path the custom peripherals module
lcper=../../libs/customperipherals/$(target)
lint The path to the header files, object files, and interface library archive file. #path the interface module
lint=../../libs/interface/$(target)
lstd | The path to the standard 'C' libraries. | #path to the standard C libraries
FLAGS Specifies compiler flags. #Compiler flags
FLAGS= -fno-inline -Wcast-align -
Wcast-qual
CFLAGS Specifies additional compiler flags. #Compiler flags
CFLAGS= -O6 -m5200 -msoft-float -
D__mod2__=void -DIN_GCC=1 -nostdinc -
gcoff3
CNFLAGS Specifies compiler flags that may be used as an alternative to CFLAGS where no optimisation is required (this can make debugging easier in certain circumstances). #Alternative compiler flags
CNFLAGS= -m5200 -msoft-float -
D__mod2__=void -DIN_GCC=1 -nostdinc -
ggcoff3
IFLAGS Specifies compiler flags associated with include file paths. #Include file path flags
IFLAGS= -I. -I$(lhdw) -I$(lper) -
I$(lcper) -I$(lint)
gnu Specifies the standard 'C' libraries to search for unresolved externals. #C libraries
gnu= -lc -ldbug -lgcc -lg -lm -
liberty -lstdc++
lib Specifies the Pluto 6 libraries to search for unresolved externals. #Pluto 6 libraries
lib= -lperipherals -
lcustomperipherals -linterface -
l$(target)
pp Specifies the command that invokes the utility to generate prototypes for a given 'C' file. #Generate prototypes
pp= cproto
as Specifies the command that invokes the GNU assembler. #Invoke the GNU assembler
as= m68k-coff-as
cc Specifies the command that invokes the GNU compiler. #Invoke the GNU compiler
cc= m68k-coff-gcc
ld Specifies the command that invokes the GNU linker. #Invoke the linker
ld = m68k-coff-ld
ar Specifies the command that invokes the GNU librarian. #Invoke the librarian
ar= m68k-coff-ar
oc This variable specifies the command that invokes the GNU object file copier. This converts the coff file format into a Motorola s-record file. #Invoke the object file copier
oc= m68k-coff-objcopy
objects Specifies the object files that are to be linked. #Objects to link
objects= game.o config.o devices.o \
demo.o custom.o sysram.o idram.o fpga.o

Implicit Rules

Implicit rules are a means of specifying to make how to generate a particular class of file from a different class of file, (for example how to generate object files from ‘C’ files). The following rules are used in the Pluto 6 make files:

Implicit Rule 1 | The first implicit rule specifies how to generate dependency (*.d) files. A dependency file names, for each object file, every source, header, and prototype file it is dependant on. This information is used by make to calculate which files must be regenerated.
Implicit Rule 2 | The second rule specifies how to generate a prototype file (*.p) from a 'C' file. The prototype file contains an 'extern' for every public function and variable defined in the 'C' file.
Implicit Rule 3 | The third rule specifies how to generate a static prototype file (*.sp) from a 'C' file. The static prototype file contains a prototype for every local function defined in the 'C' file.
Implicit Rule 4 | The fourth rule specifies how to generate an object file from a 'C' file.
Implicit Rule 5 | The fifth rule specifies how to generate an object file from an assembly file.

The Default Goal

The default goal is the target of the first non-implicit rule ‘make’ encounters. It is this file that ‘make’ endeavours to keep up to date.

In the case of the application module the default goal is the executable file defined by the variable $(output).

In the case of the custom peripherals module the default goal is the libcustomperipherals.a GNU archive library file.

Dependencies

The make file then includes all the dependency files. This means that make will scan all the dependency files and for each dependency it will make sure that the target is newer than the dependant files.

Linker Scripts

The linker script file specifies the format of the executable file generated by the linker and the addresses of the various RAM and ROM sections.

The following linker scripts for use with the application module:

Linker Script | Description
lnkdram.x | Link the code to execute from DRAM.
lnkboot.x | Link the code to execute from the boot flash.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Memory Map

ColdFire Internal Memory

The ColdFire® has a 32 bit wide data bus.
8Kbytes are organised as 2k x 32 bits.

Fast internal RAM used for the stack runs from address 0x5000 0000 to 0x5000 1fff.

The linker script defines this memory to be:

stacka : ORIGIN = 0x50000000, LENGTH = 0x00001f00
fram : ORIGIN = 0x50001f00, LENGTH = 0x000000ff

Note: The fram area is redundant and is not used.

Video RAM

The Video RAM has a 32 bit wide data bus.
The Video RAM runs from address 0x3000 0000 to 0x31ff ffff (32Mbytes of memory).

The Video driver uses some of this memory from address 0x31fc0000 to the end, to store various registers and display lists.

Memory that is left is user area, which can be used to store, for example, images and screen data.

DRAM

The DRAM has a 16 bit wide data bus.
DRAM is used for code space and contains game code.

The DRAM is 2Mbytes in size and runs from address 0x6000 0000 to 0x601f ffff.

In the Demo Project, the linker script defines this memory to be:

rom : ORIGIN = 0x60000000, LENGTH = 0x0016fefc

Note: You can store data other than code in this area by changing the linker script.

SRAM

The SRAM has an 16 bit wide data bus.
The SRAM runs from address 0x1000 0000 to 0x 1003 FFFF (256Kbytes of memory).

This memory can be subdivided into several areas:

  • Some of the memory is used by the Boot Loader (IDRAM and SYSRAM) as backed up memory (preserved on power down).
  • Some of the memory is used by the game (IDRAM and SYSRAM) as backed up memory (preserved on power down).
  • Some of the memory is used by our libraries as standard RAM.

Most of the SRAM is available to the game code.

The linker script defines this memory to be:

For the Boot Loader:

keepram : ORIGIN = 0x10000000, LENGTH = 0x00000400
ram : ORIGIN = 0x10010400, LENGTH = 0x0002fc00

In the Game Project:

keepram : ORIGIN = 0x10000400, LENGTH = 0x00001000 ram : ORIGIN = 0x10010400, LENGTH = 0x0002fc00

Flash Memory (Boot Flash)

The Boot Flash has an 8 bit wide data bus.
The Boot Flash runs from address 0x0000 0000 to 0x0007 ffff.

In the Boot Loader project, the linker script defines the memory space to be 4Mbytes:

rom : ORIGIN = 0x00000000, LENGTH = 0x003ffefc

The socket U1 on the Pluto 6 board contains a M29W040B Boot Flash device. The M29W040B is a 512Kbyte device.

Alternatively an EPROM plug in memory can be used with Pluto 6 which allows the full 4Mbyte to be implemented.

FPGA

The FPGA space starts at 0x2000 0000 and contains:

  • Lamp multiplex memory
  • Registers for 2 FPGA UARTS
  • Input/output space
  • UART routing control
  • Audio registers
  • Miscellaneous FPGA registers.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Memory Management

Memory Management

The linker is in charge of mapping different sections of the source code into physical memory on the Pluto 6 board.

SRAM (256k)

The range of memory for SRAM battery backed RAM goes from 0x10000000 to 0x1003ffff and in this range of memory three sections are created:

  • KEEPRAM for bootloader: The section is indirectly visible from there. As section starting at 0x10000000 of size 0x400 (1k) was created from the bootloader as this section was used to store the backed up data from the idram.c and sysram.c of the bootloader.
  • KEEPRAM for game: create a section from 0x10000400 of size 0x10000 (65k). This section is used to store the backed up data from the idram.c and sysram.c used in the game code.
  • RAM for game and bootloader: create a section from 0x10010400 of size 0x2fc00 (190k). This section is used to store all other data from game code.

Stack

The ColdFire® holds an 8k byte module of SRAM. As this module is directly connected to the processor, access to this data is the fastest. For this reason, Heber uses this area (stacka) to store the stack.

Rather than using the whole 8k, 256 bytes are left free (fram) in case some of this memory needs to be used in the future.

DRAM (2Mb)

Heber has allocated a single segment into the DRAM to store the game code. As it is an area of RAM, it could be used for other means such as stroring data that does not fit into the SRAM.

It is recommended you contact Customer Support, if help is required with this process, as modifying the linker could stop the Pluto 6 board from working correctly.

OUTPUT_FORMAT("coff-m68k")
MEMORY
{
        rom	: ORIGIN = 0x60000000, LENGTH = 0x001fffff
        keepram	: ORIGIN = 0x10000400, LENGTH = 0x00010000
        ram	: ORIGIN = 0x10010400, LENGTH = 0x0002fc00
        stacka  : ORIGIN = 0x50000000, LENGTH = 0x00001f00
    fram	: ORIGIN = 0x50001f00, LENGTH = 0x000000ff
}
SECTIONS
{

Fill the DRAM with:

  • the vector table from ColdFire®
  • library and user code. Code extends to constant variables.
    .vectors :
    {
        vectors_start	= .;
        ../../libs/hardware/pluto6/vectors.o(.text)
        vectors_end		= .;
    } > rom

    .text :
    {
        text_start		= .;
        checksum_start	= .;
        *(.text)

        __CTOR_LIST__ = .;
        LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)

        *(.ctors)
        LONG(0)
        __CTOR_END__ = .;

        __DTOR_LIST__ = .;
        LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
        *(.dtors)
        LONG(0)
        __DTOR_END__ = .;

        *(.lit)
        *(.shdata)
        .endcode		= .;
        endcode 		= .;
      }  > rom

    .shbss :
    {
        *(.shbss)
        text_end		= .;
        romdata_start	= .;
    } > rom

Fill the backup memory (keepram) with uninitialised variables from files idram.c and sysram.c:

    /* all unitialised data from idram.c file. */
    .id :
    {
        ram_start	= .;
        id_start	= .;
        *(.id)
        /***********************
        filename(COMMON) refers to uninitialized
        data from a particular file
        ***********************/
        idram.o(COMMON);
        id_end		= .;
    } > ram

    /* all unitialised data from idram.c file. */
    .system :
    {
        system_start	= .;
        *(.system)
        /***********************
        filename(COMMON) refers to uninitialized
        data from a particular file
        ***********************/
        sysram.o(COMMON);
        system_end		= .;
    } > ram

Fill the SRAM with variables:

  • the data segment which is the collection of all initialised global variables (ex: ULONG test_variable = 50;)
  • the bss segment is for static uninitialized data (ex: static ULONG test_variable;) Be careful, if this data is intitialised (ex: static ULONG test_variable = 50;), it will be moved into the data section but it will not appear visible
  • the common segment which is the collection of all uninitialised global variables (ex: ULONG test_variable;)
    .data : AT (ADDR(.shbss) + SIZEOF(.shbss))
    {
        vars_start	 	= .;
        *(.data)
        vars_end		=  .;
    } > ram

    checksum_end		= romdata_start + SIZEOF(.data);

    .bss ram_start + 0x00004000 :
    {
        __bss_start = .;
        bss_start	= .;
        zvars_start	 	= .;
        *(.bss)
        bss_end		= .;
        end = ALIGN(0x4);
        _end = ALIGN(0x4);
        endbssram = . ;
    } > ram

    COMMON :
    {
        __common_start	= .;
        *(COMMON)
        end = ALIGN(0x4);
        _end = ALIGN(0x4);
        zvars_end	 	= .;
        zvars_size		= zvars_end - zvars_start;
        endram = . ;
    } > ram

Allocation of the heap and stack:

    .heap :
    {
        heap_start	= .;
        . = . + 0x00005fff;
        heap_end	= .;
    } > ram

    .stack :
    {
        stack_start	= .;
        . = . + 0x00001e00;
        stack_end	= .;
    } > stacka

Section used by Heber and compiler:

    .safe :
    {
        safe_start	= . ;
        . = . + 0x000000ff;
        safe_end	= . + 1;
    } > ram

    .stab  . (NOLOAD) :
    {
        [ .stab ]
    }

    .stabstr  . (NOLOAD) :
    {
        [ .stabstr ]
    }
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Software Architecture

The following diagram illustrates the software module architecture and the drivers/functionality implemented in each module:

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Source File Types

The following file types used in the Pluto 6 software either contain, or are related to source code for the system:

.c file | C source file. The source code for the Pluto 6 is structured so that a .c file exists for each system device driver or sub-set of functionality.
.h file | .C header file that contains any defines and type definitions that are associated with in the C file of the same name. The .h file #includes the prototypes file. By including the .h file for a given .c file access is given to all of the functions and variables that are declared public in that .c file.
.p file | Prototype file that is automatically generated by the make utility. The prototype file contains the declarations for all of the public functions and variables in the given .c file.
.sp file | Static prototype file that is automatically generated by the make utility. The static prototype file contains function declarations for all of the local functions for a given .c file. This file should only be #included in the .c file of the same name.
.d file | Dependency file. The dependency file is automatically generated by the make utility, and lists paths to files upon which a .c file may be dependent.
.s file | Motorola assembly source file.
.o file | Compiled object file for a module created by the compiler.
.a file | Archive file. An archive file contains all of the compiled objects for a module, for example, libperipherals.a contains all of the objects for the peripherals module.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Software Conventions

Throughout the software and documentation the following conventions are used:

Declarations

Type Definitions | All type definitions should be in upper case e.g. typedef unsigned char BYTE;
#defines | #defines will be in upper case e.g. #define TRUE 1
Global Functions | Global function names will consist of one or more words concatenated with the first letter capitalised. e.g. void GlobalFunction( );
Static Functions | Static function names will consist of one or more words concatenated with all letters in lower case. e.g. void staticfunction( );
Global Variables | Global variables names will consist of one or more words concatenated with the first letter capitalised. e.g. BYTE GlobalVariable;
Static Variables | Static variables names will consist of one or more words concatenated with all letters in lower case. e.g. WORD staticvariable;
Local Variables | Local variables names will consist of one or more words concatenated with all letters in lower case. e.g. LONG localvariable;
Structure Elements | Structure element names will consist of one or more words concatenated with all letters in lower case e.g. Structure.element = 0;

Fundamental Data Types and #defines

BYTE | The BYTE is an 8-bit signed integer in the range -127 to +127
UBYTE | The UBYTE is an 8-bit unsigned integer in the range 0 to +255
WORD | The WORD is a 16-bit signed integer in the range -32767 to +32768
UWORD | The UWORD is a 16-bit unsigned integer in the range 0 to +65535
LONG | The LONG is a 32-bit signed integer in the range -2147483647 to +2147483648
ULONG | The ULONG is a 32-bit unsigned integer in the range 0 to +4294967295
TRUE | #define TRUE 1
FALSE | #define FALSE 0

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Demonstration Program

Pluto 6 Video Demonstration Program

Video Demonstration Program Documentation

The image files used by the video demonstration project are included on the Compact Flash card supplied as part of the Pluto 6 Development Kit. To run the video demonstration program copy the file vdemo.s19 from the video project directory to the Compact Flash card.

Component | Description
Video Demonstration Program Overview | An overview of the video demonstration project.
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Demonstration Program

Pluto 6 Video Demonstration Program Overview

The video demonstration program supplied with the Pluto 6 Development Kit shows the use of the Calypso 32 video driver API functions and provides examples of techniques that are common to video applications, for example, animation. The images used in the video demonstration are in 24 bit per pixel Windows® bitmap (.bmp) format and are loaded from Compact Flash card.

Note: Before you power up the Pluto 6 control board to run the video demonstration program ensure the Compact Flash card is fitted in the CF SLOT. The Calypso 32 Video Cards should be fitted in expansion slots EXP 0 and EXP 1 on the Pluto 6 board, and monitors are attached to the Pluto 6 VGA output connectors, P24 and P25.

Program Operation

The demonstration program runs as an automated state machine which performs the following operations:

Start Up

On start up the following steps are performed:

  • The Compact Flash card where the images are stored is mounted
  • The video card is initialised
  • The start up background images are loaded into video memory
  • The background images are displayed on the monitor
  • The animation images are loaded into video memory.

Animation Demonstration

During the animation demonstration the following steps are performed:

  • A background image is displayed on the screen
  • A border image is overlayed over the background
  • The backs of 5 cards are displayed over the background image
  • An animated message is displayed at the top of the border
  • A random number (between 1 and 5) chips of random values are displayed within the border
  • The 5 cards are rotated to display their faces
  • This sequence is then repeated.

The demonstration uses different video layers to display the background and animation sequences. The animation sequences use Double Buffering to ensure a smooth transition between frames.

See Also

  • Pluto 6 Video Driver Documentation
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


xxx API Function

Advanced Video Driver

API Function

v

Description

This.

Parameters

Parameter | Description
layer | Address of the logical layer to be cleared.
screen | Layer buffer (0 or 1 if the layer is double buffered).
width | Layer width in pixels.
bytes_per_pixel | 8 or 16 bit colour.

Return Value

None.

Code Example

xxxxx
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


2D Line Drawing

Enhanced 2D Line Drawing

The existing Video Driver uses software algorithms for 2D line drawing.
The Advanced Video Driver uses the 2D line drawing capabilities of the Cremson Video Processor.
Support for anti-aliasing, dotted lines and variable line widths are included.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Image Conversion Utilities

Image source files can be generated from standard formats (.bmp, .jpg etc) using the following Heber Utilities:

  • imagconv8.bat - for 8-bit images (generates optimum palette palette.c)
  • imagconv8std.bat - for 8-bit images (uses standard VGA palette stdpalette.c)
  • imagconv16.bat - for 16-bit images

These will produce source files image_name.c containing image data, in the following structure:

const CALYPSOIMAGE image_name = {
image parameters…
palette data.. .
bit map data ….
};

Where the type CALYPSOIMAGE is defined as:

  typedef struct calypsoimage {
  ULONG size_bytes; /* image size bytes */
  WORD color8; /* 1=8bit 0=16bit */
  WORD palette_size; /* number of palette entries */
  WORD width; /* width in pixels */
  WORD height; /* height in lines */
  const PALETTE_RGB *palette; /* palette data */
  const WORD *data; /* image data */
  } CALYPSOIMAGE;
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Unicode Characters

16-bit Unicode character codes (UTF-16) cover a range of 65536 characters.
The Advanced Video Driver divides this range into 512 code pages of 128 characters.

unicode_page | UTF-16 character range
0 | 0x0000 - 0x007F
80 | 0x0080 - 0x00FF
100 | 0x0100 - 0x017F
180 | 0x0180 - 0x01FF
FF00 | 0xFF00 - 0xFF7F
FF80 | 0xFF80 - 0xFFFF

Calypso font files contain a fixed number (128) of characters.
They can be dynamically assigned to any code page

Calypso font files are generated from standard TrueType font files using the Heber utility: fontconv.bat
Usage:

 fontconv {filename} {size} {unicode code page}

where:

{filename} | - TrueType filename without extension
{size} | - point size of font required
{unicode page} | examples:
 | 0 | - unicode range 0x0000 - 0x007F (Latin)
 | 80 | - unicode range 0x0080 - 0x00FF (Latin extended)
 | 400 | - unicode range 0x0400 - 0x047F (Cyrillic)

Examples

 True type font file: example.ttf

The following command lines:

 fontconv example 32 0
fontconv example 32 80
fontconv example 32 400

Will produce the following Calypso font files:

 example 32_0.c
example 32_80.c
example 32_400.c

Calypso font files contain font data in the following structure:

const CALYPSOFONT example32_0= {
  font parameters …
  bit-map data…
};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video and Advanced Video Operation Comparison

The underlying mechanism used to transfer instructions from the system processor to the video processor in the Advanced Video Driver differs from that used in the standard Video Driver. This page explains the different approaches implemented, and highlights the main differences.

Video Driver

The standard Video Driver instruction transfer works in the following way:

  • A video API function is called in game code
  • The API function assembles a set of instructions for the video processor to execute the requested operation
  • The set of instructions is transfered to video memory and added to the end of the list of instructions to be executed by the video processor
  • If synchronisation is required the game developer must monitor that status of the video processor to ensure that a particular set of instructions have been executed before the next set of instructions is issued

This technique is used in applications that use double buffering. The BltBusy() function is called to test the status of the video processor to ensure that all data for a screen has been written prior to flipping screens.

The following diagram provides an overview of the operation of the standard Video Driver.

Advanced Video Driver

The Advanced Video Driver instruction transfer works in the following way:

  • A video API function is called in game code
  • The API function assembles a set of instructions for the video processor to execute the requested operation
  • The set of instructions is added to the display list that is being prepared
  • When a vertical interrupt occurs the status of the video processor is queried.
  • If the video processor is not busy the display list of instructions that has been prepared is transfered to video memory
  • If the video processor is busy the display list is not transfered to video memory, and any further video intsructions issued before the next vertical interrupt are added to the list
  • When a display list has been transfered to video memory for processing a new display list is assigned for subsequent instructions
  • It is possible to schedule a display list to be transfered to video memory by calling the CalypsoFrameAdvance() function. In this way a set of commands to the video processor can be grouped for execution.
  • The Advanced Video Driver supports up to 4 display lists at any one time. The 4 display lists are handled by the Advanced Video Driver as a circular buffer: when a list has been transfered to video memory it can then be re-used in the game code. The allocation of which list to add instructions to is handled by the driver.

The scheduling of display lists with the Advanced Video Driver is handled automatically by the driver code, removing the need for the developer to monitor the status of the video processor to ensure that it is idle before issuing further commands.

The following diagram provides an overview of the operation of the Advanced Video Driver.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Pluto 6 Software

Multiplex Driver

API Function

void SetLampBrightness(const LAMP lamp, STATUS status, BYTE brightness)

Description

Set the lamp to the given status and level of brightness.

Parameters

Parameter | Description
lamp | Lamp to update
status | Lamp status
brightness | Level of brightness

Return Value

None.

Code Example

/* declare a lamp */
LAMP lamp1;
/* Set the strobe/row for the lamp using the LAMP macro */ lamp1 = LAMP(LC1, LR1); /* turn the defined lamp on at half brightness */ SetLampBrightness(lamp1, ON, 128);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


RS485 API Function

Serial Communications Driver

Reset Signal

To drive the reset signal on Pluto 6, you will use Aux6 for ccTalk1 and Aux7 for ccTalk2 in software.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Driver

The Calypso 32 Video Driver module provides an Application Programming Interface to allow the development of video based games using the Calypso 32 add on board connected to expansion slots EXP 0 or EXP 1 on the Pluto 6 board.

API Functions

The following API functions are associated with this module:

Function | Description
LoadPalette | Load a common middle/base and console layer colour palette.
SetPalette | Set a single entry in the middle/base and console layer common colour palette.
GetPalette | Read single entry from a specified palette table.
LoadCPalette | Load a console layer colour palette into video memory.
GetCPalette | Get the RGB values of the given console layer palette colour.
SetCPalette | Set the RGB value of a single entry in a console layer colour palette.
LoadMBPalette | Load a middle/base layer colour palette into video memory.
GetMBPalette | Get the RGB values of the given middle/base layer palette colour.
SetMBPalette | Set the RGB value of a single entry in a middle/base layer colour palette.
VideoOn | Enable the video display.
VideoOff | Disable the video display.
SetDisplayStart | Set the start address of the logical screens in video memory.
LoadFont | Load character font table into the video display memory.
TextColour | Set the text foreground and background colours.
SetCursor | Set the text cursor X Y co-ordinates.
VPutChar | Write a character to the screen at the text cursor position.
VPutStr | Write a string to the screen starting at the text cursor position.
PutPixel | Write a single pixel of a given colour to a screen.
GetPixel | Get the RGB colour value of a pixel at a specific X Y screen position.
SaveBackground | Save a background block to non screen memory from a logical screen.
RestoreBackground | Restore previously saved background block to a logical screen.
PutSprite | Copy an image from non screen memory to a logical screen.
ClearSprite | Clears a block from a logical screen in video memory
LoadSprite | Load a sprite from system memory into video memory and create a transparency mask of sprite.
LoadImage | Load an image into video memory.
SetDoubleBuffer | Set double buffering parameters.
ScreenFree | Determine whether a double buffered screen is free for writing.
ScreenPartitionX | Specify the right/left field partition if two partitions are used in the middle/base layers.
ScreenToggle | Enable/disable the double buffer screen toggling.
GetScreen | Return the start address of a double buffered logical screen.
InitLayer | Set the parameters for a logical screen layer.
SetWindowLayer | Initialise the window layer properties.
EnableLayer | Enable a logical screen layer so that it is displayed.
DisableLayer | Disable a logical screen layer so that it is not displayed.
ScrollLayer | Scroll a display layer by applying a horizontal or vertical offset to the display base address.
ClearLayer | Clear a logical screen layer.
ClearArea | Clear an area of a logical screen layer.
ClearBackground | Clear a background image on a given screen layer.
InitDrawframe | Initialise the drawing frame used in blit functions.
BltBusy | Get the status of a blit transfer.
Line | Draws a line of a given colour from co-ordinates.
Circle | Draws a circle of a given colour and radius.
Rectangle | Draws a rectangle of a given colour.
Create Mask | Creates and stores a mask.

See Also

  • Calypso 32 Performance Limitations
  • Calypso 32 Configuration Data
  • Calypso 32 Colour Modes
  • Calypso 32 Layer Architecture
  • Calypso 32 Transparency and Overlay Transparency
  • Double Buffering
  • Writing Text to a Screen
  • Video Defined Values
  • Transparency
  • Video/Advanced Video Driver Operational Comparison
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Blit Status API Function

Video Driver

API Function

UBYTE BltBusy ( )

Description

This function tests the status of image blitting functionality.

Parameters

None.

Return Value

Returns 1 if BLT is in progress or 0 if BLT is complete.

Code Example

/* wait for the blitter to become free */
while(BltBusy()) { };
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Area API Function

Video Driver

API Function

void ClearArea (void * layer, BYTE screen, LONG x, LONG y, LONG xsize, LONG ysize, LONG bytes_per_pixel

Description

This function performs a fast clear on a defined sub-area of a layer.

Parameters

Parameter | Description
layer | Address of the logical layer to be cleared.
screen | Screen number for double buffered layer.
x | Destination X axis logical screen co-ordinate measured from the left of the screen.
y | Destination Y axis logical screen co-ordinate measured from the left of the screen.
xsize | X axis length of the image data.
ysize | Y axis length of the image data.
bytes_per_pixel | 8 or 16 bit colour.

Return Value

None.

Code Example

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Background API Function

Video Driver

API Function

void ClearBackground (LONG screenbase, LONG xsize, LONG ysize, LONG bytes_per_pixel )

Description

This function clears a background image at given address.

Parameters

Parameter | Description
screenbase | Logical screen address of the source as an offset from the start of the video memory.
xsize | X axis length of the background image data.
ysize | Y axis length of the background image data.
bytes_per_pixel | 8 or 16 bit colour.

Return Value

None.

Code Example

None.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Layer API Function

Video Driver

API Function

void ClearLayer (void * layer, BYTE screen, LONG width, LONG bytes_per_pixel )

Description

This function clears a logical layer to black.

Parameters

Parameter | Description
layer | Address of the logical layer to be cleared.
screen | Layer buffer (0 or 1 if the layer is double buffered).
width | Layer width in pixels.
bytes_per_pixel | 8 or 16 bit colour.

Return Value

None.

Code Example

/* Clear the 8 bit base layer left partition */
ClearLayer(&Calypso32Layer[BL_LAYER], screen0, HSIZE, 1);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Clear Sprite API Function

Video Driver

API Function

void ClearSprite(LONG screenbase, LONG x, LONG y, LONG width , LONG xsize, LONG ysize, BYTE bytes_per_pixel)

Description

This function clears a block from a logical screen in video memory. It can be used to clear an area previously occupied by a sprite.

Parameters

Parameter | Description
screenbase | Logical screen address as an offset from the start of the video memory.
x | X co-ordinate start point on the logical screen of the area to clear.
y | Y co-ordinate start point on the logical screen of the area to clear.
width | Width of the logical screen.
xsize | Length of the area to clear in pixels.
ysize | Height of the area to clear in pixels.
bytes_per_pixel | Number of bytes representing each pixel (1 for 8-bit colour screen, 2 for 16-bit colour screen).

Return Value

None.

Code Example

/*
Blit a 50x50 pixel sprite to x,y co-ordinates 100,100 on 16 bit logical screen 0
in transparent mode from offscreen memory
*/
PutSprite(screen0, 100,100, offscreen, 50, 50, 1, 2);

/* clear the area occupied by the sprite to black */
ClearSprite(screen0, 100, 100, HSIZE , 50, 50, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Create Mask API Function

Video Driver

API Function

LONG CreateMask(const UBYTE* startaddr, LONG offset, LONG size ,LONG bytes_per_pixel)

Description

Creates a mask from an image save at startaddr.
Stores mask at video base memory address + offset.

Remarks

In order to have the transparency parameter working with putsrite function, a mask needs to be created for each sprite. When loading images from compact flash, the mask operation is not done and it is strongly recommended to create the mask right after loading an image from compact flash.

Parameters

Parameter | Description
startaddr | Address of sprite image.
offset | Offset from video memory to beginning of mask.
size | Size of sprite image to mask in bytes.
bytes_per_pixel | 16 or 8 bit colour.

Return Value

Offset from start of video memory to end of mask.

Code Example

/*loading the image ball from compact flash as per video project*/
(ULONG) ball.start_address = (ULONG)*freememoryptr;
if (loadwindowsbmp("ball.bmp", &ball.bmpinfo, scratch_memoryptr, freememoryptr))
{
    TxString(serialdevice,serialchannel,"Failed to load ball.bmp\r");
    return FALSE;
}
else
    TxString(serialdevice,serialchannel,"ball.bmp loaded\r");

/* create a mask on this image */
(ULONG) ball_mask.start_address = (ULONG)*freememoryptr;	/*start address of the mask*/
ball_mask.bmpinfo.imagewidth=ball.bmpinfo.imagewidth;
ball_mask.bmpinfo.imageheight=ball.bmpinfo.imageheight;

    (ULONG)*freememoryptr+=CreateMask((const UBYTE*)(ball.start_address),	/*start address of the image to mask*/
        ball_mask.start_address-OFFSET_VIDEO_MEMORY,	/*offset where to store the mask from start of video memory */
        ball.bmpinfo.imagewidth*ball.bmpinfo.imageheight* BYTES_PER_PIXEL, /*nb of bytes to mask*/
        BYTES_PER_PIXEL);	/*colour width of the image to mask*/
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Disable Layer API Function

Video Driver

API Function

void DisableLayer (UBYTE select )

Description

This function disables a logical layer.

Remarks

Refer to the Video Driver Defined Values page for a list defined layers to use with this function.

Parameters

Parameter | Description
select | Layer to disable.

Return Value

None.

Code Example

/* Disable the console layer */
DisableLayer(CONSOLE_ENABLE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Draw Circle API Function

Video Driver

API Function

void Circle(LONG screenbase, LONG xcentre, LONG ycentre, LONG radius, UWORD colour, LONG bytes_per_pixel)

Description

Draw a circle of a given colour and radius, with its centre at co-ordinates xcentre, ycentre on an 8 or 16 bit colour screen.

Parameters

Parameter | Description
screenbase | Offset from the start of the video memory.
xcentre | Centre x co-ordinate.
ycentre | Centre y co-ordinate.
radius | Circle radius.
colour | Colour of the circle.
bytes_per_pixel | Number of bytes representing each pixel (1 for 8-bit colour screen, 2 for 16-bit colour screen).

Return Value

None.

Code Example

/*
Draw a green circle with a radius of 100 pixels at the centre of an 800x600
16-bit logical screen defined as screen0
 */
Circle(screen0, 400, 300, 100, 0x001F, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Draw Line API Function

Video Driver

API Function

void Line(LONG screenbase, LONG Ax, LONG Ay, LONG Bx, LONG By, UWORD colour, LONG bytes_per_pixel)

Description

Draw a line of a given colour from co-ordinates Ax, Ay to co-ordinates Bx, By on an 8 or 16 bit colour screen.

Parameters

Parameter | Description
screenbase | Offset from the start of the video memory.
Ax | Line origin x co-ordinate.
Ay | Line origin y co-ordinate.
Bx | Line end point x co-ordinate.
By | Line end point y co-ordinate.
colour | Colour of the line.
bytes_per_pixel | Number of bytes representing each pixel (1 for 8-bit colour screen, 2 for 16-bit colour screen).

Return Value

None.

Code Example

/*
Draw a red diagonal line from the centre of an 800x600 display to the top
left corner of a 16-bit logical screen defined as screen0
 */
Line(screen0, 400, 300, 0, 0, 0x7C00, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Draw Rectangle API Function

Video Driver

API Function

void Rectangle(LONG screenbase, LONG left, LONG top, LONG right, LONG bottom, UWORD colour, LONG bytes_per_pixel)

Description

Draw a rectangle of a given colour from co-ordinates top, left to co-ordinates bottom, right on an 8 or 16 bit colour screen.

Parameters

Parameter | Description
screenbase | Offset from the start of the video memory.
left | Left start point co-ordinate.
top | Top start co-ordinate.
right | Right end point co-ordinate.
bottom | Bottom end point co-ordinate.
bytes_per_pixel | Number of bytes representing each pixel (1 for 8-bit colour screen, 2 for 16-bit colour screen).

Return Value

None.

Code Example

/*
Draw a red rectangle 100 pixels wide and 50 pixels high starting at co-ordinates
100,100 on a 16-bit logical screen defined as screen0
 */
Rectangle(screen0, 100, 100, 200, 150, 0x7C00, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Enable Layer API Function

Video Driver

API Function

void EnableLayer (UBYTE select )

Description

This function enables a logical layer.

Remarks

Refer to the Video Driver Defined Values page for a list defined layers to use with this function.

Parameters

Parameter | Description
select | Layer to enable.

Return Value

None.

Code Example

/* Enable the base layer */
EnableLayer(BASE_ENABLE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get C Palette API Function

Video Driver

API Function

void GetCPalette (UBYTE table_entry RGB * colour )

Description

This function reads a single RGB entry in the colour palette for the console display layer from table position table_entry. The result is stored in colour.

Parameters

Parameter | Description
table_entry | The number of the entry in the RGB palette table.
colour | The address of the colour value read from palette table at position table_entry.

Return Value

None.

Code Example

/* define colour variable */
RGB colour;

/*
Read palette entry 16 from the console layer palette into variable colour
 */
GetCPalette(16, &colour);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get MB Palette API Function

Video Driver

API Function

void GetMBPalette (UBYTE table_entry RGB * colour )

Description

This function reads a single RGB entry in the colour palette for the middle/base layers from table position table_entry. The result is stored in colour.

Parameters

Parameter | Description
table_entry | The number of the entry in the RGB palette table.
colour | The address of the colour value read from palette table at position table_entry.

Return Value

None.

Code Example

/* define colour variable */
RGB colour;

/*
Read palette entry 16 from the middle/base layer palette into variable colour
 */
GetMBPalette(16, &colour);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Palette API Function

Video Driver

API Function

void GetPalette (UBYTE table_entry RGB * colour )

Description

This function reads a single RGB entry in the colour palettes for the middle/base and console display layers from table position table_entry. The result is stored in colour.

Parameters

Parameter | Description
table_entry | The number of the entry in the RGB palette table.
colour | The address of the colour value read from palette tables at position table_entry.

Return Value

None.

Code Example

/* define colour variable */
RGB colour;

/* Read palette entry 16 into variable colour */
GetPalette(16, &colour);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Pixel API Function

Video Driver

API Function

UWORD GetPixel(LONG screenbase, LONG x, LONG y, LONG bytes_per_pixel)

Description

This function returns the colour value of a pixel on a logical screen at co-ordinates X Y.

Remarks

This function will only currently work on 8-bit colour logical screens.

Parameters

Parameter | Description
screenbase | Logical screen address as an offset from the start of the video memory.
x | X axis logical screen co-ordinate measured from the left of the screen.
y | Y axis logical screen co-ordinate measured from the top of the screen.
bytes_per_pixel | Number of bytes representing each pixel (1 for 8-bit colour screen, 2 for 16-bit colour screen)

Return Value

The colour value at the specified location.

Code Example

/* variable to store colour value */
UWORD pixel_value;
/*
read colour value of a pixel at x,y co-ordinates 100,100 on the defined 16 bit screen
*/
pixel_value = GetPixel(screen0 ,100 ,100, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Get Screen API Function

Video Driver

API Function

LONG GetScreen (BYTE screen )

Description

This function returns the start address of the a given buffer within a double buffered screen.

Parameters

Parameter | Description
screen | Double buffer screen 0 or 1.

Return Value

The address of the given screen.

Code Example

/* variable to store the start address of the screen */
LONG screen_offset;
/*
get the start address in video memory of screen 0 as an offset from the
video base address
 */
screen_offset = GetScreen(screen0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Init Draw Frame API Function

Video Driver

API Function

void InitDrawframe (WORD mode, LONG base WORD xres )

Description

This function initialises a drawing frame.

Remarks

Drawing frames are used to define a screen memory address and dimensions for use with text functions. The cursor x,y co-ordinates that are used to write a character to a logical screen are relative to the start address of the drawing frame. For further information on text functions and drawing frames please refer to the Writing Text to a Screen page.

Parameters

Parameter | Description
mode Layer Mode
Mode = 0x8000 - 16 bit colour
Mode = 0x0000 - 8 bit colour
base | Base address of the drawing frame memory.
xres | Drawing frame horizontal resolution in pixels.

Return Value

None.

Code Example

/*
initialise an 8 bit  drawing frame of width HSIZE starting at the memory address
defined as screen 1
 */
InitDrawframe(0, screen1, HSIZE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Init Layer API Function

Video Driver

API Function

void InitLayer (void * layer, BYTE colour_mode, BYTE flip_mode, WORD transparent_colour, WORD width, WORD height, LONG orig_adr0, LONG disp_adr0, LONG orig_adr1, LONG disp_adr1, )

Description

This function defines the intial parameters of a logical display layer.

Remarks

Refer to the Video Driver Defined Values page for a list of defined configuration values. For information on configuring double buffered layers refer to the Double Buffering page.

Parameters

Parameter | Description
layer | Address of the Calypso 32 layer structure.
colour_mode | 8 or 16 bit colour.
flip_mode | Single or double buffered.
transparent_colour | Layer transparency colour.
width | Layer width in pixels. This value must be multiple of 64 bytes and be greater than or equal to HSIZE, the horizontal display width.
height | Layer height in pixels.
orig_adr0 | Base Address of logical graphics field: Memory address of top left pixel.
disp_adr0 | Base Address of display frame: Top left position address.
orig_adr1 | Base Address of logical graphics field: Memory address of top left pixel.
disp_adr1 | Base Address of display frame: Top left position address.

Return Value

None.

Code Example

a) Initialise a layer to be a single screen layer:
/*
Initialise the middle left layer with the following parameters:
Colour mode = 16 bit colour
Double buffering = One screen for the layer
Transparent colour = white
Horizontal size = width of screen display from configuration data
Vertical size = height of screen display from configuration data
Origin and display address are set to the same memory address
as double buffering is not enabled
 */
InitLayer(&Calypso32Layer[ML_LAYER], DIRECT_COLOR, LAYER_FRAME0, 0x7fff, HSIZE,
VSIZE, screen1, screen1, screen1, screen1);

b) Initialise a layer to be a double buffer layer:
/*
Initialise the middle left layer with the following parameters:
Colour mode = 16 bit colour
Double buffering = Double buffer between screen 0 and screen 1
Transparent colour = white
Horizontal size = width of screen display from configuration data
Vertical size = height of screen display from configuration data
*/
InitLayer(&Calypso32Layer[ML_LAYER], DIRECT_COLOR, LAYER_FRAME0, 0x7fff, HSIZE,
VSIZE, screen0, screen0, screen1, screen1);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load C Palette API Function

Video Driver

API Function

void LoadCPalette (const RGB * palette_table )

Description

This function loads the RGB colour palette for the console display layer.

Parameters

Parameter | Description
palette_table | The address of the RGB colour palette table.

Return Value

None.

Code Example

/*
Load an 8-bit palette table for the console layer
*/
LoadCPalette(stdpalette_table);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Font API Function

Video Driver

API Function

void LoadFont (const ULONG * font )

Description

This function loads an 8-bit font from Pluto 6 system memory into video memory.

Remarks

Font source files can be generated from standard font files(.ttf) using supplied Heber Utilities.
For Further information on Heber font conversion utilities see Font Conversion Utilities.

Parameters

Parameter | Description
font | Start address of font data.

Return Value

None.

Code Example

/* load tempo 16 point font file into video memory */
LoadFont(tempo16);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Image API Function

Video Driver

API Function

LONG LoadImage (const UBYTE * startaddr, LONG offset, LONG size )

Description

This function loads an image from a given address into video memory and returns the next video memory address following the image data.

Remarks

This function will work with both 8 and 16 bit images.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Parameters

Parameter | Description
startaddr | The start address of the image to be loaded.
offset | The offset from the start of video memory where the image is to be loaded to.
size | The size of the image in pixels.

Return Value

Returns the next memory address following the image data.

Code Example

/* address where image is to be loaded to in video memory */
LONG screen0;
/* next free address following the loaded image */
LONG free;

/* Load 16 bit background image */
free = LoadImage(bgnd, screen0, bgnd_width * bgnd_height * BYTES_PER_PIXEL);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load MB Palette API Function

Video Driver

API Function

void LoadMBPalette (const RGB * palette_table )

Description

This function loads the RGB colour palettes for the middle/base display layers.

Parameters

Parameter | Description
palette_table | The address of the RGB colour palette table.

Return Value

None.

Code Example

/*
Load an 8-bit palette table for the middle/base layers
*/
LoadMBPalette(stdpalette_table);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Palette API Function

Video Driver

API Function

void LoadPalette (const RGB * palette_table )

Description

This function loads the RGB colour palettes for the middle/base and console display layers.

Parameters

Parameter | Description
palette_table | The address of the RGB colour palette table.

Return Value

None.

Code Example

/*
Load an 8-bit palette table for both middle/base and console layers
*/
LoadPalette(stdpalette_table);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Load Sprite API Function

Video Driver

API Function

LONG LoadSprite (const UBYTE * startaddr, LONG offset, LONG size , LONG bytes_per_pixel)

Description

Loads a sprite from startaddr in system memory to video base memory address + offset. It also load transparency mask of sprite immediately after sprite in video memory.

Remarks

This function is used to load a sprite created in .s format from system memory to video memory. This function is not suitable for loading large background images. In such a case the LoadImage() function should be used.

Image source files can be generated from standard formats (.bmp, .jpg etc) using supplied Heber Utilities.
For Further information on Heber image conversion utilities see Image Conversion Utilities.

Parameters

Parameter | Description
startaddr | The start address of the image to be loaded.
offset | The offset from the start of video memory where the image is to be loaded to.
size | The size of the image in pixels.
bytes_per_pixel | 8 or 16 bit colour.

Return Value

This function returns the offset from start of video memory to end of mask.

Code Example

/* address where sprite is to be loaded to in video memory */
LONG imabckgnd_8bit;
LONG imabckgnd_16bit;
/* next free address following the loaded sprite transparency mask*/
LONG ball_offset;

/* Load 8 bit sprite imabckgnd */
ball_offset =LoadSprite((const UBYTE*)imabckgnd_8bit ,imabckgnd_8bit_offset, imabckgnd_8bit_width * imabckgnd_8bit_height,1);

/* Load 16 bit sprite imabckgnd */
ball_offset =LoadSprite((const UBYTE*) imabckgnd_16bit, imabckgnd_16bit_offset,imabckgnd_16bit_width * imabckgnd_16bit__height,1);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Write Pixel API Function

Video Driver

API Function

void PutPixel (LONG screen, LONG x, LONG y, UWORD colour, LONG bytes_per_pixel)

Description

This function sets the colour of a pixel on a logical screen at co-ordinates X Y.

Remarks

This function will only currently work on 8-bit colour logical screens.

Parameters

Parameter | Description
screenbase | Logical screen address as an offset from the start of the video memory.
x | X axis logical screen co-ordinate measured from the left of the screen.
y | Y axis logical screen co-ordinate measured from the top of the screen.
colour | Pixel colour value.
bytes_per_pixel | Number of bytes representing each pixel (1 for 8-bit colour screen, 2 for 16-bit colour screen).

Return Value

None.

Code Example

/*
write a red pixel to x,y co-ordinates 200,200 on the defined 16 bit screen
*/
PutPixel(screen0 ,200, 200, 0x7C00, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Put Sprite API Function

Video Driver

API Function

void PutSprite (LONG screenbase, LONG dest_x, LONG dest_y, LONG dest_width, LONG src_image_start, LONG src_xsize, LONG src_ysize, LONG mode, LONG bytes_per_pixel )

Description

This function copies an image block from a buffer in video memory to a logical screen with optional transparent background.

Remarks

This function will work with both 8 and 16 bit colour logical screens and images.

For further information, see also Transparency.

Parameters

Parameter | Description
screenbase | Logical screen address of the source as an offset from the start of the video memory.
dest_x | Destination X axis logical screen co-ordinate measured from the left of the screen.
dest_y | Destination Y axis logical screen co-ordinate measured from the top of the screen.
screen_width | Width of the destination logical screen in pixels.
src_image_start | Address in video memory where the image data starts.
src_xsize | X axis length of the image data.
src_ysize | Y axis length of the image data.
mode | Transparency Mode. 0 = normal mode, 1 = transparent mode.
bytes_per_pixel | 8 or 16 bit colour mode source data.

Return Value

None.

Code Example

/*
Blit a 50x50 pixel sprite to x,y co-ordinates 100,100 on 16 bit logical
screen 0 in transparent mode from offscreen memory
*/
PutSprite(screen0, 100,100, HSIZE, offscreen, 50, 50, 1, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Restore Background API Function

Video Driver

API Function

void RestoreBackground (LONG screenbase, LONG x, LONG y, LONG save_address, LONG xsize, LONG ysize, LONG bytes_per_pixel )

Description

This function restores a previously saved background block of image data from a buffer area of video memory to a logical screen.

Remarks

This function will work with both 8 and 16 bit colour logical screens.

Parameters

Parameter | Description
screenbase | Logical screen address of the source as an offset from the start of the video memory.
x | Destination X axis logical screen co-ordinate measured from the left of the screen.
y | Destination Y axis logical screen co-ordinate measured from the top of the screen.
save_address | Address in video memory where the background block was saved.
xsize | X axis length of the saved data.
ysize | Y axis length of the saved data.
bytes_per_pixel | bytes_per_pixel 8 or 16 bit colour mode source data.

Return Value

None.

Code Example

/*
Restore a previously saved 50 by 50 area from a 16 bit logical screen to
x,y co-ordinates 100,100 on logical screen1
*/
RestoreBackground(screen1, 100,100, offscreen, 50, 50, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Save Background API Function

Video Driver

API Function

void SaveBackground (LONG screenbase, LONG x, LONG y, LONG save_address, LONG xsize, LONG ysize, LONG bytes_per_pixel )

Description

This function saves a background block of image data to a buffer area of video memory from a logical screen.

Remarks

This function will work with both 8 and 16 bit colour logical screens.

Note: There is a hardware limitation with the Cremson Video Controller. The chip can only blit correctly blocks with widths that are a multiple of 8 bytes.

This imposes the following limitation with SaveBackground():

  1. Horizontal size must be multiple of 8 pixels (8 bit colour).
  2. Horizontal size must be multiple of 4 pixels (16 bit colour).

Parameters

Parameter | Description
screenbase | Logical screen address of the source as an offset from the start of the video memory.
x | X axis logical screen co-ordinate measured from the left of the screen of the source data.
y | Y axis logical screen co-ordinate measured from the top of the screen of the source data.
save_address | Address in video memory where the background block will be saved.
xsize | X axis length of the source data.
ysize | Y axis length of the source data.
bytes_per_pixel | 8 or 16 bit colour mode source data.

Return Value

None.

Code Example

/*
Save a 100 by 100 area of 8 bit logical screen 0 starting at x,y co-ordinates 10,10
to offscreen memory
*/
SaveBackground(screen0, 10,10, offscreen, 100, 100, 2);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Screen Free API Function

Video Driver

API Function

BYTE ScreenFree (BYTE screen )

Description

This function tests the status of a given screen buffer when using double buffering. If the given buffer is currently being displayed it can not be updated and the function will return FALSE. If the given buffer is not being displayed the function will return TRUE and the buffer can be updated.

Parameters

Parameter | Description
screen | The buffer to be tested.

Return Value

Return TRUE if the given buffer is free for writing.
Return FALSE if it is not free for writing.

Code Example

/* wait for the screen to become free */
while(!(ScreenFree(screen))) {};
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Screen Partition API Function

Video Driver

API Function

void ScreenPartitionX(WORD x)

Description

This function specifies the right/left field partition if two partitions are used in the middle/base layers.

Parameters

Parameter | Description
x | Partition position X must satisfy the following: 1 <= x <= HSIZE

Return Value

None.

Code Example

/* Set screen partition position to 100 pixels on the x axis */
ScreenPartitionX(100)
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Screen Toggle API Function

Video Driver

API Function

void ScreenToggle (WORD enable )

Description

This function allows the toggling of the two buffers used in double buffering to be disabled while the offscreen buffer is updated, and then enabled to allow the updated buffer to be displayed.

Parameters

Parameter | Description
enable | Value to enable or disable double buffer screen toggling.

Return Value

None.

Code Example

/* enable screen toggling */
ScreenToggle(ENABLE);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Scroll Layer API Function

Video Driver

API Function

void ScrollLayer (void * layer, ULONG xoff, ULONG yoff )

Description

Scroll a display layer by applying a horizontal or vertical offset to the display base address. The offset is applied during the next vertical interrupt.

Parameters

Parameter | Description
layer | Address of the Calypso 32 layer structure.
xoff | Horizontal offset in bytes. 8 bit colour mode: 1 byte = 1 pixel 16 bit colour mode: 2 bytes = 1 pixel xoff must satisfy the following: 0 <= xoff <= layer width (8 bit colour) 0 <= xoff <= 2*layer width (16 bit colour)
yoff | Vertical offset in pixels

Return Value

None.

Code Example

/* scroll the base layer left partition by 20 pixels horizontally */
ScrollLayer(&Calypso32Layer[BL_LAYER], 20, 0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set C Palette API Function

Video Driver

API Function

void SetCPalette (UBYTE table_entry RGB * colour )

Description

This function initialises a single entry in the RGB colour palette for the console display layer with colour at position table_entry.

Parameters

Parameter | Description
table_entry | The number of the entry in the RGB palette table.
colour | Address of colour value to enter into the console layer palette table at position table_entry.

Return Value

None.

Code Example

/* define colour variable */
RGB colour;

/*
Read palette entry 20 from the console layer palette into variable colour
*/
GetCPalette(20, &colour);

/* change colour */
colour.red+=10;
colour.green+=10;
colour.blue+=10;

/* write new colour back to console layer palette */
SetCPalette(20, &colour);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Cursor API Function

Video Driver

API Function

void SetCursor (WORD x, WORD y )

Description

This function sets X Y co-ordinates for a text cursor prior to writing a character to a logical screen.

Remarks

The X and Y cursor co-ordinates are used as an offset into a drawing frame, and must be set prior to writing characters to the screen. A drawing frame must be set up for a particular logical layer using the InitDrawFrame() function before text can be written to the layer. This function will only work with 8-bit logical screens.

Font source files can be generated from standard font files(.ttf) using supplied Heber Utilities.
For Further information on Heber font conversion utilities see Font Conversion Utilities.

Parameters

Parameter | Description
x | X axis logical screen co-ordinate measured from the left of the screen.
y | Y axis logical screen co-ordinate measured from the top of the screen.

Return Value

None.

Code Example

/* Set a drawing frame to logical screen defined as screen0 */
InitDrawFrame(0, screen0, HSIZE);

/* Set the cursor the x,y co-ordinates 20,20 in the drawing frame */
SetCursor(20, 20);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Display API Function

Video Driver

API Function

void SetDisplayStart (ULONG screen_start_address )

Description

This function is used to set the start address in video memory used to store the logical layer display screen areas.

Parameters

Parameter | Description
screen_start_address | The start address of logical screen memory.

Return Value

None.

Code Example

/* declare a logical screen */
LONG screen0;

/* define a memory location for the logical screen */
screen0 = 0;

/*
Set the offset into video memory that is to be used as the screen start
*/
SetDisplayStart(screen0);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Double Buffer API Function

Video Driver

API Function

void SetDoubleBuffer (LONG scrn0, LONG scrn1, BYTE rate )

Description

This function sets the refresh rate for all the layers initialised as double buffered layers (see InitLayer). The two areas of memory defined for these layers will then toggle at the same screen rate on a vertical interrupt signal.

Remarks

Refer to the Video Driver Defined Values page for a list of supported screen refresh rates. Base and middle layers cannot be set to update on individual refresh rate. They will both update at the same screen rate.

Parameters

Parameter | Description
scrn0 | Not used.
scrn1 | Not used.
rate | The screen refresh rate in Hz.

Return Value

None.

Code Example

/*
Set all layers defined to be double buffer to toggle at a refresh rate of 20Hz
*/
SetDoubleBuffer(0,0,FRAME20HZ);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set MB Palette API Function

Video Driver

API Function

void SetMBPalette (UBYTE table_entry RGB * colour )

Description

This function initialises a single entry in the RGB colour palette for the middle/base display layers with colour at position table_entry.

Parameters

Parameter | Description
table_entry | The number of the entry in the RGB palette table.
colour | Address of colour value to enter into the middle/base layer palette tables at position table_entry.

Return Value

None.

Code Example

/* define colour variable */
RGB colour;

/*
Read palette entry 10 from the middle/base layer palette into variable colour
*/
GetMBPalette(10, &colour);

/* change colour */
colour.red+=5;
colour.green+=5;
colour.blue+=5;

/* write new colour back to middle/base layer palette */
SetMBPalette(10, &colour);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Palette API Function

Video Driver

API Function

void SetPalette (UBYTE table_entry RGB * colour )

Description

This function initialises a single entry in the RGB colour palettes for the middle/base and console display layers with colour at position table_entry.

Parameters

Parameter | Description
table_entry | The number of the entry in the RGB palette table.
colour | colour Address of colour value to enter into the palette tables at position table_entry.

Return Value

None.

Code Example

/* define colour variable */
RGB colour;

/* Read palette entry 16 into variable colour */
GetPalette(16, &colour);

/* change colour */
colour.red+=20;
colour.green+=20;
colour.blue+=20;

/* write new colour back to palette */
SetPalette(16, &colour);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Window Layer API Function

Video Driver

API Function

void SetWindowLayer (WORD xpos, WORD ypos, WORD width, WORD height )

Description

This function sets the Window layer properties.

Parameters

Parameter | Description
xpos | X co-ordinate
ypos | Y co-ordinate
width | layer width
height | layer height

Remarks

The Window layer differs from the other 3 logical layers as it has a variable screen size and position where all other layers are full screen. It is initialised using the InitLayer() function using the following parameter settings:

Window Layer Initialisation Parameters

Parameter | Description
layer | W_LAYER
colour_mode | DIRECT_COLOUR(16 bit colour)
flip_mode | not used (set to 0)
transparent_colour | not used (set to 0)
width | not used (set to 0)
height | not used (set to 0)
orig_adr0 | Base Address of logical graphics field: Memory address of top left pixel.
disp_adr0 | Base Address of display frame: Top left position address.
orig_adr1 | not used (set to 0)
disp_adr1 | not used (set to 0)

Initialisation Code Example

/*
Initialise the window layer */
InitLayer(&Calypso32Layer[W_LAYER], DIRECT_COLOR, 0, 0, HSIZE, 0, screen1,
screen1, 0, 0);

Return Value

None.

Code Example

/* set a 200x200 pixel window at x,y co-ordinates 100,100 */
SetWindowLayer( 100, 100, 200, 200);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Set Text Colour API Function

Video Driver

API Function

void TextColour (UWORD foreground_colour, UWORD background_colour )

Description

This function sets the colour of the actual text and the text background using 8-bit colour values. This function supports the use of transparent backgrounds.

Remarks

Font source files can be generated from standard font files(.ttf) using supplied Heber Utilities.
For Further information on Heber font conversion utilities see Font Conversion Utilities.

Parameters

Parameter | Description
foreground_colour | Actual colour of the characters using 8-bit colour.
background_colour | 8-bit colour of the character background.

Return Value

None.

Code Example

/* Set the foreground colour to white and background colour to red */
TextColour(WHITE, RED);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Off API Function

Video Driver

API Function

void VideoOff ( )

Description

This function is used to disable the video display.

Parameters

None.

Return Value

None.

Code Example

/* disable the monitor */
VideoOff();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video On API Function

Video Driver

API Function

void VideoOn ( )

Description

This function is used to enable the video display. It is called when the video driver is installed and does not not need to be called again unless the display is disabled using the Vide0Off() function.

Parameters

None.

Return Value

None.

Code Example

/* enable the monitor */
VideoOn();
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Write Character API Function

Video Driver

API Function

void VPutChar (UBYTE character )

Description

This function writes a 7-bit ascii character to video display at the current X Y text cursor position.

Remarks

The X Y co-ordinates are updated to the next valid writing position on the logical screen after writing a character. Carriage Return (CR) and Line Feed (LF) characters are supported.

Font source files can be generated from standard font files(.ttf) using supplied Heber Utilities.
For Further information on Heber font conversion utilities see Font Conversion Utilities.

Parameters

Parameter | Description
character | The 7-ascii code for the character to be written to the screen.

Return Value

None.

Code Example

/* Set a drawing frame to logical screen defined as screen0 */
InitDrawFrame(0, screen0, HSIZE);

/* Set the cursor the x,y co-ordinates 20,20 in the drawing frame */
SetCursor(20, 20);

/*
write the character A to the x,y co-ordinates in the drawing frame defined
*/
VPutChar('A');
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Write String API Function

Video Driver

API Function

void VPutStr (const BYTE * text_string )

Description

This function writes a null-terminated 7-bit ascii character string to the video display starting at the current X Y text cursor position.

Remarks

The X Y co-ordinates are updated to the next valid writing position on the logical screen after writing the string.

Font source files can be generated from standard font files(.ttf) using supplied Heber Utilities.
For Further information on Heber font conversion utilities see Font Conversion Utilities.

Parameters

Parameter | Description
text_string | Address of 7-bit ascii character string to be written to the screen.

Return Value

None.

Code Example

/* Set a drawing frame to logical screen defined as screen0 */
InitDrawFrame(0, screen0, HSIZE);

/* Set the cursor the x,y co-ordinates 10,10 in the drawing frame */
SetCursor(10, 10);

/*
write a string starting at co-ordinates x,y in the drawing frame defined
*/
VPutString("Text String");
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Double Buffering - Clearing a Layer

This code example shows how Double Buffering is implemented by clearing a layer:

void Double_Buffer_Method_1 (void)
/*
    Single buffer background layer
    Double buffer sprite layer
    Entire sprite layer cleared each update
*/
{
    /* video memory - start address for layers */
    ULONG base_screen0, base_screen1, middle_screen0, middle_screen1, offscreen,
    free;

    /* video memory - start address for images*/
    ULONG bgnd_offset, sprite_offset;

    /* sprite  animation parameters */
    LONG x, y;
    LONG dx, dy;
    LONG xsave[2], ysave[2];
    ULONG hsize = 800;

    UBYTE screen;	/* current NON displayed screen */

    /* video memory */
    base_screen0		= 0;
    base_screen1		= base_screen0;
    middle_screen0	= base_screen1	+ (HSIZE*VSIZE*BYTES_PER_PIXEL);
    middle_screen1	= middle_screen0	+ (HSIZE*VSIZE*BYTES_PER_PIXEL);
    offscreen 		= middle_screen1	+ (HSIZE*VSIZE*BYTES_PER_PIXEL);

    /* BASE Layer: background image - single buffered */
    InitLayer(&Calypso32Layer[BL_LAYER], DIRECT_COLOR, LAYER_FRAME0, BLACK,
        HSIZE, VSIZE, base_screen0, base_screen0, base_screen1,
        base_screen1);
    ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, BYTES_PER_PIXEL);
    EnableLayer(BASE_ENABLE);

    /* MIDDLE Layer: sprite plane - double buffered */
    InitLayer(&Calypso32Layer[ML_LAYER], DIRECT_COLOR, LAYER_FRAME0, BLACK,
        HSIZE, VSIZE, middle_screen0, middle_screen0, middle_screen1,
        middle_screen1);
    ClearLayer(&Calypso32Layer[ML_LAYER], 0, HSIZE, BYTES_PER_PIXEL);
    ClearLayer(&Calypso32Layer[ML_LAYER], 1, HSIZE, BYTES_PER_PIXEL);
    EnableLayer(MIDDLE_ENABLE);

    /* load background and sprite images into non displayed video memory */
    bgnd_offset	= offscreen;
    sprite_offset	= LoadSprite((const UBYTE*)bgnd,   bgnd_offset,
        BYTES_PER_PIXEL*bgnd_width*bgnd_height,BYTES_PER_PIXEL);
    free		= LoadSprite((const UBYTE*)sprite, sprite_offset,
        BYTES_PER_PIXEL*sprite_width* sprite_height, BYTES_PER_PIXEL);

    /* load background image to base layer */
    PutSprite(base_screen0, 0, 0, HSIZE, bgnd_offset, bgnd_width , bgnd_height, 0,
        BYTES_PER_PIXEL);

    /* initial position and velocity of animated sprite */
    x = 0; y = 0;
    dx = 10; dy = 10;
    xsave[0]=0; ysave[0]=0; xsave[1]=0; ysave[1]=0;

    /* enable double buffering */
    SetDoubleBuffer(0,0,FRAME60HZ);
    screen = 0;

    while(1) {

        while(!ScreenFree(screen))
            ;

        /***	Clear the entire sprite layer: SLOW! ***/
        ClearLayer(&Calypso32Layer[ML_LAYER], screen, HSIZE, BYTES_PER_PIXEL);

        while(BltBusy())	    /* ensure command finished */
            ;

        /*** next location:boundary conditions-bounce off screen sides ***/
        x += dx; y += dy;
        if (y < 0)		   { dy = -dy; y = 0; }
        if (y > VSIZE - sprite_height){ dy = -dy; y = VSIZE - sprite_height; }
        if (x < 0)		   { dx = -dx; x = 0; }
        if (x > hsize - sprite_width){ dx = -dx; x = hsize - sprite_width; }
        xsave[screen] = x; ysave[screen] = y;

        /*** Put Sprite ***/
        PutSprite((screen+2)*HSIZE*VSIZE*BYTES_PER_PIXEL, x, y, HSIZE,
            sprite_offset, sprite_width , sprite_height, 0,
            BYTES_PER_PIXEL);

        while(BltBusy())	    /* ensure command finished */
            ;

        ScreenToggle(ENABLE);    /* toggle screen on next vertical
        interrupt */
        screen = !screen;	    /*next screen */

    }

}

See Also

  • Double Buffering - Clearing a Sprite
  • Double Buffering - Saving/Restoring Sprite Area
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Double Buffering - Clearing the Sprite

This code example shows how Double Buffering is implemented by clearing the sprite:

void Double_Buffer_Method_2 (void)
/*
    Single buffer background layer
    Double buffer sprite layer
    Sprite cleared each update
*/
{
    /* video memory - start address for layers */
    ULONG base_screen0, base_screen1, middle_screen0, middle_screen1, offscreen,
    free;

    /* video memory - start address for images*/
    ULONG bgnd_offset, sprite_offset;

    /* sprite  animation parameters */
    LONG x, y;
    LONG dx, dy;
    LONG xsave[2], ysave[2];
    ULONG hsize = 800;

    UBYTE screen;	/* current NON displayed screen */

    /* video memory */
    base_screen0	= 0;
    base_screen1		= base_screen0;
    middle_screen0	= base_screen1	+ (HSIZE*VSIZE*BYTES_PER_PIXEL);
    middle_screen1	= middle_screen0	+ (HSIZE*VSIZE*BYTES_PER_PIXEL);
    offscreen 		= middle_screen1	+ (HSIZE*VSIZE*BYTES_PER_PIXEL);

    /* BASE Layer: background image - single buffered */
    InitLayer(&Calypso32Layer[BL_LAYER], DIRECT_COLOR, LAYER_FRAME0, BLACK,
        HSIZE, VSIZE, base_screen0, base_screen0, base_screen1, base_screen1);
    ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, BYTES_PER_PIXEL);
    EnableLayer(BASE_ENABLE);

    /* MIDDLE Layer: sprite plane - double buffered */
    InitLayer(&Calypso32Layer[ML_LAYER], DIRECT_COLOR, LAYER_FRAME0, BLACK,
        HSIZE, VSIZE, middle_screen0, middle_screen0, middle_screen1,
        middle_screen1);
    ClearLayer(&Calypso32Layer[ML_LAYER], 0, HSIZE, BYTES_PER_PIXEL);
    ClearLayer(&Calypso32Layer[ML_LAYER], 1, HSIZE, BYTES_PER_PIXEL);
    EnableLayer(MIDDLE_ENABLE);

    /* load background and sprite images into non displayed video memory */
    bgnd_offset	= offscreen;
    sprite_offset	= LoadSprite((const UBYTE*)bgnd,   bgnd_offset,
        BYTES_PER_PIXEL*bgnd_width*bgnd_height, BYTES_PER_PIXEL);
    free		= LoadSprite((const UBYTE*)sprite, sprite_offset,
        BYTES_PER_PIXEL*sprite_width* sprite_height, BYTES_PER_PIXEL);

    /* load background image to base layer */
    PutSprite(base_screen0, 0, 0, HSIZE, bgnd_offset, bgnd_width , bgnd_height, 0,
        BYTES_PER_PIXEL);

    /* initial position and velocity of animated sprite */
    x = 0; y = 0;
    dx = 10; dy = 10;
    xsave[0]=0; ysave[0]=0; xsave[1]=0; ysave[1]=0;

    /* enable double buffering */
    SetDoubleBuffer(0,0,FRAME60HZ);
    screen = 0;

    while(1) {

        while(!ScreenFree(screen))
            ;

        /*** clear the sprite at last coordinate: FASTER ***/
        ClearSprite((screen+2)*HSIZE*VSIZE*BYTES_PER_PIXEL, xsave[screen] ,
            ysave[screen], HSIZE, sprite_width, sprite_height,
            BYTES_PER_PIXEL);

        /*** next location: boundary conditions - bounce off screen sides ***/
        x += dx; y += dy;
        if (y < 0)		    { dy = -dy; y = 0; }
        if (y > VSIZE - sprite_height){ dy = -dy; y = VSIZE - sprite_height; }
        if (x < 0)		    { dx = -dx; x = 0; }
        if (x > hsize - sprite_width){ dx = -dx; x = hsize - sprite_width; }
        xsave[screen] = x; ysave[screen] = y;

        /*** Put Sprite ***/
        PutSprite((screen+2)*HSIZE*VSIZE*BYTES_PER_PIXEL, x, y, HSIZE,
            sprite_offset, sprite_width , sprite_height, 0,
            BYTES_PER_PIXEL);

        while(BltBusy())		/* ensure command finished */
            ;

        ScreenToggle(ENABLE);	/* toggle screen on next vertical
        interrupt */
        screen = !screen;		/* next screen */

    }

}

See Also

  • Double Buffering - Clearing a Layer
  • Double Buffering - Saving/Restoring Sprite Area
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Double Buffering

Double Buffering

Double buffering is a technique used for displaying flicker free animations. The Base and Middle display layers support Double Buffering on the Cremson Video processor.

There are three methods of double buffering:

  1. By clearing a layer (Separate sprite layer).
  2. By clearing the sprite (Separate sprite layer).
  3. By saving/restoring sprite area (Combined sprite/background layer).

Click on the above links for code examples, illustrating each of these methods.

Implementing Double Buffering

Double buffering is implemented on the Calypso 32 by assigning two areas of video memory to a display layer. Whilst one of the areas is being displayed the image data on the other can be updated. When the update is complete the screens are switched and the updated data is displayed. This technique prevents partially updated images from being displayed.

The following API functions are related to the implementation double buffering on the Calypso 32:

Function | Description
InitLayer(); | This function initialises a layer for use. When a double buffered layer is initialised the two buffers for the screen are defined.
ClearLayer(); | This function is used to clear the buffers that have been defined for the layer. Parameter 2 (screen) can be set the either 0 for the first buffer or 1 for the second buffer.
SetDoubleBuffer(); | This function sets the display refresh rate. For a list of supported refresh rates refer to the Video Defined Values page.
ScreenFree(); | This function is used to determine whether a screen is free (not being displayed) prior to updating it.
ScreenToggle(); | This function is used to switch between buffers.
BltBusy() | This function is used to ensure all commands have been executed by video controller.

Code Example

The following code example initialises the base left layer as a 16 bit layer. Two buffers are defined for the layer and double buffering is enabled. Two sprites are loaded into video memory. The program then enters a loop in which manual double buffering is implemented. An image is copied to the off screen buffer, and then screen toggling is enabled to allow the current off and on screen buffers to be swapped during the next vertical interrupt so that the updated buffer is displayed. Following the screen swap the process is repeated.

/* logical screen address variables */
LONG screen0;
LONG screen1;
LONG sprite1;
LONG sprite2;
LONG free;

/*
variables to contain information for the sprite that is currently
being copied to the offscreen buffer
*/
LONG current_sprite;
LONG current_sprite_width;
LONG current_sprite_height;

/* flag for current display buffer */
LONG screen_flag;

/* set 16 bit logical screen addresses in video memory */
screen0 = 0;
screen1 = HSIZE*VSIZE*BYTESPERPIXEL;

/* set screen flag to screen 0 */
screen_flag = 0;

/*
set screen 0 and screen 1 as buffers to use for double buffering
with a refresh rate of 60Hz
*/
SetDoubleBuffer(screen0, screen1, FRAME60HZ);

/* disable the base layer */
DisableLayer(BASE_ENABLE);

/*
Initialise the base layer left partition as:
16 bit
initial display buffer screen 0
transparent colour BLACK
horizontal and vertical dimensions to fill the whole display
logical screen 0 in video memory for buffer 1
logical screen 1 in video memory for buffer 2
2 bytes per pixel data
*/
InitLayer(&Calypso32Layer[BL_LAYER], DIRECT_COLOR, LAYER_FRAME0,
BLACK, HSIZE, VSIZE, screen0, screen0, screen1, screen1);

/* clear the video memory for the base layer buffers to black */
ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, 2);
ClearLayer(&Calypso32Layer[BL_LAYER], 1, HSIZE, 2);

/* enable the base layer */
EnableLayer(BASE_ENABLE);

/* load two 16 bit sprites called p5 and p6 */
free = LoadSprite(((const UBYTE*)p5, sprite1, p5_width*p5_height*2);
free = LoadSprite(((const UBYTE*)p6, sprite2, p6_width*p6_height*2);

current_sprite = sprite1;
current_sprite_width = p5_width;
current_sprite_height= p5_height;

while(TRUE)
{
    /* wait for screen to become free */
    while(!(ScreenFree(screen_flag)))
    {

    };

    /* copy image to offscreen memory buffer */
    PutSprite(screen_flag*HSIZE*VSIZE*2, 100, 100, HSIZE,
    current_sprite ,current_sprite_width, current_sprite_height, 0, 2);

    /* enable screen toggling because offscreen update is complete */
    ScreenToggle(ENABLE);

    /*
    switch screens and update current sprite data
    */
    if(!screen_flag)
    {
        screen_flag = !screen_flag;
        current_sprite = sprite2;
        current_sprite_width = p6_width;
        current_sprite_height= p6_height;
    }
    else
    {
        screen_flag = !screen_flag;
        current_sprite = sprite1;
        current_sprite_width = p5_width;
        current_sprite_height= p5_height;
    }
}
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Saving/Restoring Sprite Area

Double Buffering - Saving/Restoring Sprite Area

This code example shows how Double Buffering is implemented by saving/restoring the sprite area:

void Double_Buffer_Method_3 (void)
/*
    Double buffer combined  background and sprite layer
    Sprite area saved/restored each update
*/
{
    /* video memory - start address for layers */
    ULONG base_screen0, base_screen1, offscreen, free;

    /* video memory - start address for images*/
    ULONG bgnd_offset, sprite_offset;

    /* sprite  animation parameters */
    LONG i, x, y;
    LONG dx, dy;
    LONG xsave[2], ysave[2];
    ULONG hsize = 800;

    /* current NON displayed screen */
    UBYTE screen;

    /* video memory */
    base_screen0	= 0;
    base_screen1	= base_screen0 + (HSIZE*VSIZE*BYTES_PER_PIXEL);
    offscreen 	= base_screen1 + (HSIZE*VSIZE*BYTES_PER_PIXEL);

    /* BASE Layer: background image AND sprites - double buffered */
    InitLayer(&Calypso32Layer[BL_LAYER], DIRECT_COLOR, LAYER_FRAME0,
    BLACK, HSIZE, VSIZE, base_screen0, base_screen0, base_screen1,
    base_screen1);
    ClearLayer(&Calypso32Layer[BL_LAYER], 0, HSIZE, BYTES_PER_PIXEL);
    ClearLayer(&Calypso32Layer[BL_LAYER], 1, HSIZE, BYTES_PER_PIXEL);
    EnableLayer(BASE_ENABLE);

    /* load background and sprite images into non displayed video memory */
    bgnd_offset	= offscreen;
    sprite_offset	= LoadSprite((const UBYTE*)bgnd,   bgnd_offset,
        BYTES_PER_PIXEL*bgnd_width*bgnd_height,      BYTES_PER_PIXEL);
    free		= LoadSprite((const UBYTE*)sprite, sprite_offset,
        BYTES_PER_PIXEL*sprite_width* sprite_height, BYTES_PER_PIXEL);

    /* load background image to base layer (both screens) */
    PutSprite(base_screen0, 0, 0, HSIZE, bgnd_offset, bgnd_width , bgnd_height, 0,
        BYTES_PER_PIXEL);
    PutSprite(base_screen1, 0, 0, HSIZE, bgnd_offset, bgnd_width , bgnd_height, 0,
        BYTES_PER_PIXEL);

    /* initial position and velocity of animated sprite */
    x = 0; y = 0;
    dx = 10; dy = 15;
    xsave[0]=0; ysave[0]=0; xsave[1]=0; ysave[1]=0;

    /* enable double buffering */
    SetDoubleBuffer(0,0,FRAME60HZ);
    screen = 0;
    i=0;

    while(1) {

        while(!ScreenFree(screen))
            ;

        /*** restore sprite background ***/
        if(i<2)
            i++;
        else
            RestoreBackground ((screen+2)*HSIZE*VSIZE*BYTES_PER_PIXEL,
                xsave[screen], ysave[screen], sprite_offset,
                sprite_width, sprite_height, BYTES_PER_PIXEL);

        /* next location: boundary conditions - bounce off screen sides */
        x += dx; y += dy;
        if (y < 0) 			{ dy = -dy; y = 0; }
        if (y > VSIZE - sprite_height)	{ dy = -dy; y = VSIZE
                         - sprite_height; }
        if (x < 0)			{ dx = -dx; x = 0; }
        if (x > hsize - sprite_width)	{ dx = -dx; x = hsize
                        - sprite_width; }
        xsave[screen] = x; ysave[screen] = y;

        /*** save sprite background ***/
        SaveBackground ((screen+2)*HSIZE*VSIZE*BYTES_PER_PIXEL, x, y,
            sprite_offset, sprite_width , sprite_height,
            BYTES_PER_PIXEL);

        /*** Put Sprite ***/
        PutSprite((screen+2)*HSIZE*VSIZE*BYTES_PER_PIXEL, x, y, HSIZE,
            sprite_offset, sprite_width , sprite_height, 0,
            BYTES_PER_PIXEL);

        while(BltBusy())		/* ensure command finished */
            ;

        ScreenToggle(ENABLE);	/* toggle screen on next vertical
        interrupt */
        screen = !screen;		/* next screen */

    }

}

See Also

  • Double Buffering - Clearing a Layer
  • Double Buffering - Clearing the Sprite
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Configuration Data

The following structure in the config.c file in the project directory allows configuration of the video processor for specific display dimensions.

/* Calypso 32 Video */
const	CALYPSO32CFG	Calypso32Cfg[]=
{
    /*
    set the screen size to 800x600 and the standard palette for 8 bit colour
    */
    {Cremson800x600,stdpalette_table},
    0
};

Supported Display Resolutions

The following display resolutions are supported by the video processor and can be used for video driver configuration:

Resolution | Configuration Value
640x480 | Cremson640x480
768x576 | Cremson768x576
800x600 | Cremson800x600
1024x768 | Cremson1024x768
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Video Defined Values

Screen Refresh Rates

The following refresh rates are supported by the video driver for use with double buffering:

Label | Meaning
SINGLE_BUFFER | One screen buffer
FRAME60HZ | 60Hz refresh rate
FRAME30HZ | 30Hz refresh rate
FRAME20HZ | 20Hz refresh rate
FRAME15HZ | 15Hz refresh rate
FRAME12HZ | 12Hz refresh rate
FRAME10HZ | 10Hz refresh rate
FRAME5HZ | 5Hz refresh rate
FRAME3HZ | 3Hz refresh rate
FRAME2HZ | 2Hz refresh rate
FRAME1HZ | 1Hz refresh rate

Colour Modes

The video processor supports the following defined colour modes for the Base, Middle and Console layers. The Window layer is 16 bit Direct Colour only.

Label | Meaning
INDIRECT_COLOUR | 8 bit colour
DIRECT_COLOUR | 16 bit colour

Screen Buffer Modes

The video processor supports the following screen buffer modes on the Base and Middle layers. The Window and Console layers are single buffered.

Label | Meaning
LAYER_FRAME0 | Manual frame flipping. The screen defined in orig_adr0 will initially displayed.
LAYER_FRAME1 | Manual frame flipping. The screen defined in orig_adr1 will initially displayed.
LAYER_FRAMEFLIP | Hardware frame flipping performed every vertical interrupt.

Video Processor Layers

The video processor implements 4 display layers, 2 of which can be divided into 2 separate areas.

Label | Meaning
C_LAYER | Console layer
W_LAYER | Window layer
ML_LAYER | Middle left layer
MR_LAYER | Middle right layer
BL_LAYER | Base left layer
BR_LAYER | Base right layer

Enabling/disabling Video Processor Layers

The following definitions can be when enabling/disabling video layers:

Label | Meaning
CONSOLE_ENABLE | Console layer
WINDOW_ENABLE | Window layer
MIDDLE_ENABLE | Middle layer
BASE_ENABLE | Base layer

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Calypso 32 Text to a Screen

Writing Text to a Screen

The video device driver provides functionality to allow the game developer to write text to the video display. The driver currently supports 8 bit font files, so can therefore only be used to write text to screens defined as 8 bit (INDIRECT_COLOUR).

The following functions are used to write text to a screen:

Function | Description
InitDrawframe(); | This function sets up a drawing frame relative to the logical screen defined in video memory on to which the text is to be written.
LoadFont(); | This function loads a prepared font file from system memory to video memory.
TextColour(); | This function set the background and foreground colours for the characters displayed.
SetCursor(); | This function sets the cursor position in the drawing frame where the next character will be drawn. The cursor position is incremented following after the character is drawn. If the edge of the drawing frame is reached the cursor position will word wrap to the next line position of the screen.
VputChar(); | This function draws a single character.
VputString(); | This function draws a character string.

Cursor Position

The origin position within a drawing frame (x,y co-ordinate 0,0) is at the top left of the drawing frame.

The origin position of a character bit map in a font file (x,y co-ordinate 0,0) is at the bottom left of the character.

When setting the cursor position to write text a drawing frame the y axis co-ordinate must be set to the desired position + the height of the character in pixels to ensure that the character is displayed.

Code Example

To display a character that is 20 pixels high in the top left of the display the cursor y position must set to the drawing frame y origin + 20.

/*
set the cursor position to the top left of the drawing frame
for a 20 pixel high font
 */
SetCursor(0,20);

Code Example

The following code example initialises two layers (base and middle) in 8 bit mode and writes characters to both using the tempo 16 point font.

/* logical screen address variables */
LONG screen0;
LONG screen1;

/* set logical screen addresses in video memory */
screen0 = 0;
screen1 = HSIZE*VSIZE;

/* disable the base and middle layers */
DisableLayer(BASE_ENABLE);
DisableLayer(MIDDLE_ENABLE);

/* set to start of video memory */
SetDisplayStart(screen0);

/*
Initialise the base layer left partition as:
8 bit
single buffer
transparent colour BLACK
horizontal and vertical dimensions to fill the whole display
logical screen 0 in video memory
1 byte per pixel data
*/
InitLayer(&Calypso32Layer[BL_LAYER], INDIRECT_COLOR, LAYER_FRAME0,
BLACK, HSIZE, VSIZE, screen0, screen0, screen0, screen0);

/* clear the video memory for the base display layer to black */
ClearLayer(&Calypso32Layer[BL_LAYER], screen0, HSIZE, 1);

/*
Initialise the middle layer left partition as:
8 bit
single buffer
transparent colour BLACK
horizontal and vertical dimensions to fill the whole display
logical screen 1 in video memory
1 byte per pixel data
*/
InitLayer(&Calypso32Layer[ML_LAYER], INDIRECT_COLOR, LAYER_FRAME0,
BLACK, HSIZE, VSIZE, screen1, screen1, screen1, screen1);

/* clear the video memory for the middle display layer to black */
ClearLayer(&Calypso32Layer[ML_LAYER], screen1, HSIZE, 1);

/* enable the base and middle layers */
EnableLayer(BASE_ENABLE);
EnableLayer(MIDDLE_ENABLE);
/*
Initialise the text drawing frame for the base layer in 8 bit mode starting at
logical screen 0 set to the width of the whole screen
*/
InitDrawframe(0, screen0, HSIZE);

/* load the tempo 16 point font into video memory */
LoadFont(tempo16);

/* set the text colour to BLUE foreground and BLACK background */
TextColour(BLUE, BLACK);

/*
set the cursor position for the first character to x,y co-ordinates
100,100 relative to the start address of the drawing frame
*/
SetCursor(100,100);

/* write a character string to the base layer */
VPutStr("The quick brown fox jumps over the lazy dog. ");

/*
Initialise the text drawing frame for the middle layer in 8 bit mode starting
at logical screen 1 set to the width of the whole screen
*/
InitDrawframe(0, screen1, HSIZE);

/* set the text colour to WHITE foreground and BLACK background */
TextColour(WHITE, BLACK);

/*
set the cursor position for the first character to x,y co-ordinates
100,100 relative to the start address of the drawing frame
*/
SetCursor(200,200);

/* write a single character to the screen */
VputChar(‘A’);
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Stop Channel API Function

Streamed Audio Driver

API Function

void StopAudioChannel(BYTE audioChannel)

Description

This function stops an audio sample currently playing on the specified channel. This function differs from the QuiteChannel() function in the following ways:

  • The audio file that was playing is not closed
  • The audio file that was playing is rewound to the start of the file

This function should be used in the case when an audio sample is repeatedly stopped and restarted.

Parameters

Parameter | Description
audioChannel | Audio channel to stop sample playing on. Refer to the Streamed Audio Driver Defined Values page for the defined channels.

Return Value

None.

Code Example

/* Stop audio sample and rewind file */
StopAudioChannel( AUDIO_LEFT1 );
© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Command Line Tools

The tools and utilities supplied with the Pluto 6 Development Kit can be run from a Command Prompt under Windows® 2000 and Windows® XP.

No Command Line Tool documentation is currently available.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.


Video Driver Font Conversion Utility (ttf2gnu.bat)

This utility will convert .ttf true type font files into .s assembler files. The converted font files can be used in game projects.

Note: This utility does not support Unicode fonts.

Using the Utility

  1. Create a directory in the root directory of your drive called tmp (for example C:\tmp). This is required for the tool to work correctly.
  2. Copy the font file that you wish to convert into the your project directory.
  3. Open a DOS window and change directory to your project directory.
  4. The conversion utilites requires the following parameters:
    filename | - without file extension
    size | - point size of the font

To convert the font file type:
ttf2gnu <filename> <size> and press enter.

Note: This utility will only accept filenames in a DOS 8.3 format. The initial TTF file must only have 6 characters, so when combined with the point size, it does not create a filename greater than 8 characters before the .BDF extension.

Example

To convert the font file comic.ttf at 32 point size type:
ttf2gnu comic 32

This will create a file called comic.s which can be used in a game project.

Font Size Support

The Calypso 32 video processor will only support font sizes up to a maximum of 32 points.

Note: Certain characters, for example, @ and % will not be displayed correctly if a font size of 32 points is used. This is because the Cremson driver allows a maximum pixel size of 32 and the conversion tool uses a specified point size. Pixel size and point size are approximately but not exactly the same, hence certain characters will not display correctly.

© HEBER LTD. 2009. This document and the information contained therein is the intellectual property of Heber Ltd. and must not be disclosed to a third party without consent. Copies may be made only if they are in full and unmodified. The information contained in this documentation is believed to be accurate and reliable. However, Heber Ltd. assumes no responsibility for its use, and reserves the right to revise the documentation without notice.