PICASO Internal Functions
Note
The older format of the internal functions manual is included in Workshop4 installation and can be found under:
C:\Users\Public\Documents\4D Labs\4DUpdates\Manuals
You can also download this document below:
Introduction
The 4D Labs family of embedded graphics processors are powered by a highly optimised soft-core virtual engine, E.V.E. (Extensible Virtual Engine). EVE was designed and created by 4D Labs in the early 2000’s and should not be confused by FTDI’s solution of EVE, which was developed a decent decade or so later.
EVE is a proprietary, high performance virtual processor with an extensive byte-code instruction set optimised to execute compiled 4DGL programs. 4DGL (4D Graphics Language) was specifically developed from ground up for the EVE engine core. It is a high-level language which is easy to learn and simple to understand yet powerful enough to tackle many embedded graphics applications.
4DGL is a graphics-oriented language allowing rapid application development. An extensive library of graphics, text and file system functions and the ease of use of a language that combines the best elements and syntax structure of languages such as C, Basic, Pascal, etc. Programmers familiar with these languages will feel right at home with 4DGL. It includes many familiar instructions such as IF..ELSE..ENDIF, WHILE..WEND, REPEAT..UNTIL, GOSUB..ENDSUB, GOTO as well as a wealth of (chip-resident) internal functions that include SERIN, SEROUT, GFX_LINE, GFX_CIRCLE and many more.
This document covers the internal (chip-resident) functions available for the PICASO Processor. This document should be used in conjunction with the 4DGL Programmers Reference Manual.
PICASO Internal Block Diagram
Internal Functions Summary
PICASO Internal functions can be categorized based on usage as listed below:
- C Type Functions
- Display I/O Functions
- FAT16 File Functions
- Flash Memory Functions
- General Purpose Functions
- GPIO Functions
- Graphics Functions
- I2C Master Functions
- Image Control Functions
- Math Functions
- Media Functions
- Memory Allocation Functions
- Serial (UART) Functions
- Sound Control Functions
- SPI Control Functions
- String Class Functions
- System Memory Functions
- Text and String Functions
- Timer Functions
- Touch Screen Functions
C Type Functions
isdigit
Tests the character parameter and returns a 1 if the character is an ASCII digit else returns a 0. Valid range: "0123456789".
Syntax: isdigit(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Return: 0 if character is not as ASCII digit, 1 if character is an ASCII digit.
Example
func main()
var ch;
var stat;
gfx_Cls();
txt_Set(FONT_ID, FONT2);
print("Serial Input Test\n");
print("Downloading prog to flash\n");
print("Then use debbug terminal\n");
to(COM0); print("serial input test:\n");
// now just stay in a loop
repeat
ch := serin();
if (ch != -1)
print( [CHR] ch ); // if a key was received from PC,
// print its ascii value
if (isdigit(ch)) print(“Character is an ASCII digit”);
if (isxdigit(ch)) print(“Character is ASCII Hexadecimal”);
if (isupper(ch)) print(“Character is ASCII uppercase letter”);
if (islower(ch)) print(“Character is ASCII uppercase letter”);
if (isalpha(ch)) print(“Character is an ASCII uppercase or lowercase”);
if (isalnum(ch)) print(“Character is an ASCII Alphanumeric”);
if (isprint(ch)) print(“Character is a printable ASCII”);
if (isspace(ch)) print(“Character is a space type character”);
endif
forever // this as well
endfunc
isxdigit
Tests the character parameter and returns a 1 if the character is an ASCII hexadecimal digit else returns a 0. Valid range: "0123456789ABCDEF".
Syntax: isxdigit(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not as ASCII hexadecimal digit, 1 if character is an ASCII hexadecimal digit.
Example: Refer to isdigit Example
isupper
Tests the character parameter and returns a 1 if the character is an ASCII upper case letter else returns a 0. Valid range: "ABCDEF....WXYZ".
Syntax: isupper(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not as ASCII upper case letter, 1 if character is an ASCII upper case letter.
Example: Refer to isdigit Example
islower
Tests the character parameter and returns a 1 if the character is an ASCII lower case letter else returns a 0. Valid range: "abcd....wxyz".
Syntax: islower(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not as ASCII lower case letter, 1 if character is an ASCII lower case letter.
Example: Refer to isdigit Example
isalpha
Tests the character parameter and returns a 1 if the character is an ASCII lower or upper case letter else returns a 0. Valid range : "abcd....wxyz", “ABCD....WXYZ”
Syntax: isalpha(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not as ASCII lower or upper case letter, 1 if character is an ASCII lower or upper case letter.
Example: Refer to isdigit Example
isalnum
Tests the character parameter and returns a 1 if the character is an ASCII Alphanumeric else returns a 0. Valid range : "abcd....wxyz", “ABCD....WXYZ”, “0123456789”
Syntax: isalnum(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not as ASCII Alphanumeric character, 1 if character is an ASCII Alphanumeric character.
Example: Refer to isdigit Example
isprint
Tests the character parameter and returns a 1 if the character is a printable ASCII character else returns a 0. Valid range : 0x20... 0x7F
Syntax: isprint(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not a printable ASCII character, 1 if character is a printable ASCII character.
Example: Refer to isdigit Example
isspace
Tests the character parameter and returns a 1 if the character is any one of the space type character else returns a 0. Valid range : space, formfeed, newline, carriage return, tab, vertical tab.
Syntax: isspace(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: 0 if character is not a space type character, 1 if character is a space type character.
Example: Refer to isdigit Example
toupper
Tests the character parameter and if the character is a lower cases letter, it returns the upper case equivalent else returns the passed char. Valid range: "abcd ... wxyz".
Syntax: toupper(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: The upper case equivalent if characters are lower case else returns the passed char.
Example
func main()
var ch, Upconvch, Loconvch, stat;
gfx_Cls();
txt_Set(FONT_ID, FONT2);
print ("Serial Input Test\nDownload prog to flash\n");
print ("Then use debug terminal\n");
to(COM0); print("serial input test:\n");
repeat // now just stay in a loop
ch := serin();
if (ch != 1) // if a key was received from PC,
print([CHR]ch); // print its ascii value
if (isupper(ch))
print("Uppercase ASCII found. Converting to lowercase");
Loconvch := tolower(ch);
endif
if (islower(ch))
print("Lowercase ASCII found. Converting to Uppercase");
Upconvch := toupper(ch);
endif
endif
forever
endfunc
tolower
Tests the character parameter and if the character is a lower case letter it returns the upper case equivalent else returns the passed char. Valid range: "ABCD ... WXYZ".
Syntax: toupper(char);
| Arguments | Description |
|---|---|
| char | Specifies the ASCII character for the test. |
Returns: The lower case equivalent if characters are upper case else returns the passed char.
Example
Refer to toupper Example.
LObyte
Returns the lower byte (lower 8-bit) of a 16-bit variable.
Syntax: LObyte(var);
| Arguments | Description |
|---|---|
| var | User variable. |
Returns: The lower byte (lower 8-bit) of a 16-bit variable.
Example
HIbyte
Returns the upper byte (upper 8-bits) of a 16-bit variable.
Syntax: HIbyte(var);
| Arguments | Description |
|---|---|
| var | User variable. |
Returns: The upper byte (upper 8-bit) of a 16-bit variable.
Example
ByteSwap
Returns the swapped upper and lower bytes of a 16-bit variable.
Syntax: ByteSwap(var);
| Arguments | Description |
|---|---|
| var | User variable. |
Returns: Returns the endian swapped value of a 16-bit variable.
Example
Display I/O Functions
These functions allow direct display access for fast blitting operations.
disp_SetReg
Sets the Display driver IC register.
Syntax: disp_SetReg(register, data);
| Arguments | Description |
|---|---|
| register | Refer to the display driver datasheet |
| data | Refer to the display driver datasheet |
Returns: None
disp_setGRAM
Prepares the GRAM area for user access. The lower 16bits of the pixel count in the selected area is returned. This is usually all that is needed unless GRAM area exceeds 256^2. A copy of the 32bit value can be found in GRAM_PIXEL_COUNT_LO and GRAM_PIXEL_COUNT_HI.
Syntax: disp_setGRAM(x1, y1, x2, y2);
| Arguments | Description |
|---|---|
| x1, y1 | Top left of the GRAM window. |
| x2, y2 | Bottom right of the GRAM window. |
Returns: The LO word of the 32-bit pixel count is returned.
Example
disp_WrGRAM
Data can be written to the GRAM consecutively using this function once the GRAM access window has been set up.
Syntax: disp_WrGRAM(colour);
| Arguments | Description |
|---|---|
| colour | Pixel color to be populated. |
Returns: None
Example
disp_WriteControl
Sends a 16-bit value to the display bus. Refer to individual data sheets for the display for more information. This function is used to extend the capabilities of the user code to gain access to the display hardware.
Syntax: disp_WriteControl(value);
| Arguments | Description |
|---|---|
| value | Specifies the 16-bit value to be written to the display control register. |
Returns: None
Example
disp_WriteWord
Sends a 16-bit value to the display bus. Refer to individual data sheets for the display for more information. This function is used to extend the capabilities of the user code to gain access to the display hardware.
Syntax: disp_WriteWord(value);
| Arguments | Description |
|---|---|
| value | Specifies the value to be written to the display data register. |
Returns: None
Example
disp_ReadWord
Read a word from the display.
Syntax: disp_ReadWord(value);
| Arguments | Description |
|---|---|
| value | Specifies the value to be read to the display data register. |
Returns: 16-bit value in the register.
Example
disp_Sync
Allows the program to synchronise writing to the hardware for flicker free operation. Some
experimentation may be needed to find an optimum line for disp_Sync depending on the graphics
operation. The higher the value, the slower the throughput. A certain point will be reached (number
of scanlines + blanking lines within the vertical retrace period) where it will just 'hang up' stopping
the entire process. Eg, in 640x480 mode, if the 'lines' value is 507, operation will be slowest (as its
actually right at the end of the blanking period) and 508 will cause a hangup situation as it is above
the highest scanline value.
Syntax: disp_Sync(line);
| Arguments | Description |
|---|---|
| line | Scan line. |
Returns: 16-bit value in the register.
Note
Applies to uVGA-II/III modules only.
disp_Disconnect
This function disconnects the display driver pins and/or reconfigures it to achieve its lowest possible power consumption. Use after disabling peripheral power to ensure the minimal power usage by the display.
Syntax: disp_Disconnect();
Returns: None
Note
disp_Init() should be used to reinitialise the display.
disp_Init
This function is used to initialise the display. This is useful in a number of situations, however mainly for the uLCD-xx-PTU modules which have the ability to disable the power supply to the display for low power sleep modes. This function is required to re-initialise the display once power to the display has been restored, so the display is usable once again.
Syntax: disp_Init();
Returns: None
FAT16 File Functions
file_Error
Returns the most recent error code or 0 if there were no errors.
File Error Codes
| Error Code | Value | Description |
|---|---|---|
| FE_OK | 0 | IDE function succesded |
| FE_IDE_ERROR | 1 | IDE command execution error |
| FE_NOT_PRESENT | 2 | CARD not present |
| FE_PARTITION_TYPE | 3 | WRONG partition type, not FAT16 |
| FE_INVALID_MBR | 4 | MBR sector invalid signature |
| FE_INVALID_BR | 5 | Boot Record invalid signature |
| FE_MEDIA_NOT_MNTD | 6 | Media not mounted |
| FE_FILE_NOT_FOUND | 7 | File not found in open for read |
| FE_INVALID_FILE | 8 | File not open |
| FE_FAT_EOF | 9 | Fat attempt to read beyond EOF |
| FE_EOF | 10 | Reached the end of file |
| FE_INVALID_CLUSTER | 11 | Invalid cluster value > maxcls |
| FE_DIR_FULL | 12 | All root dir entry are taken |
| FE_MEDIA_FULL | 13 | All clusters in the partition are taken |
| FE_FILE_OVERWRITE | 14 | A file with same name exist already |
| FE_CANNOT_INIT | 15 | Cannot init the CARD |
| FE_CANNOT_READ_MBR | 16 | Cannot read the MBR |
| FE_MALLOC_FAILED | 17 | Malloc could not allocate the FILE struct |
| FE_INVALID_MODE | 18 | Mode was not r.w. |
| FE_FIND_ERROR | 19 | Failure during FILE search |
| FE_INVALID_FNAME | 20 | Invalid Filename |
| FE_INVALID_MEDIA | 21 | bad media |
| FE_SECTOR_READ_FAIL | 22 | Sector Read fail |
| FE_SECTOR_WRITE_FAIL | 23 | Sector Write fail |
Syntax: file_Error();
Returns: Error Code
Example
file_Count
Returns number of files found that match the criteria. The wild card character '*' matches up with any combination of allowable characters and '?' matches up with any single allowable character.
Syntax: file_Count(filename);
| Arguments | Description |
|---|---|
| filename | Name of the file(s) for the search (passed as a string). |
Returns: Number of files that match the criteria.
Example
file_Dir
Streams a string of file names that agree with the search key. Returns number of files found that match the criteria. The wild card character '*' matches up with any combination of allowable characters and '?' matches up with any single allowable character.
Syntax: file_Dir(filename);
| Arguments | Description |
|---|---|
| filename | Name of the file(s) for the search (passed as a string). |
Returns: Number of files that match the criteria.
Example
file_FindFirst
Returns true if at least 1 file exists that satisfies the file argument.
Wildcards are usually used so if file_FindFirst returns true, further tests can be made using file_FindNext(); to find all the files that match the wildcard class. Note that the stream behaviour is the same as file_Dir.
Syntax: file_FindFirst(fname);
| Arguments | Description |
|---|---|
| fname | Name of the file(s) for the search (passed as a string). |
Return: 1 If at least one file exists that satisfies the criteria. 0 If no file satisfies the criteria.
Example
file_FindNext
Returns true if more file exists that satisfies the file argument that was given for file_FindFirst. Wildcards must be used for file_FindFirst, else this function will always return zero as the only occurrence will have already been found. Note that the stream behaviour is the same as file_Dir.
Syntax: file_FindNext();
Returns: 1 if more files exist that satisfy the criteria set in the file_FindFirst(fname). 0 if no more files satisfy the criteria set in the file_FindFirst(fname)
Example
file_Exists
Tests for the existence of the file provided with the search key. Returns TRUE if found.
Syntax: file_Exists(fname);
| Arguments | Description |
|---|---|
| fname | Name of the file(s) for the search (passed as a string). |
Return: 1 if File found. 0 if File not found.
Example
file_Close
Returns TRUE if file closed, FALSE if not.
Syntax: file_Close();
| Arguments | Description |
|---|---|
| fname | the file handle that was created by file_Open("fname") which is now used as reference (handle) for "fname" for further file functions such as in this function to close the file. |
Returns: True (1) if file closed, False (0) otherwise.
Example
file_Open
Returns handle if file exists. The file "handle" that is created is now used as reference for "filename" for further file functions such as file_Close(handle), etc. For FILE_WRITE and FILE_APPEND modes ('w' and 'a') the file is created if it does not exist.
If the file is opened for append, and it already exists, the file pointer is set to the end of the file ready for appending, else the file pointer will be set to the start of the newly created file.
If the file was opened successfully, the internal error number is set to 0 (i.e. no errors) and can be read with the file_Error() function.
For FILE_READ mode ('r') the file must exist else a null handle (0) is returned and the 'file not found' error number is set which can be read with the file_Error() function.
Syntax: file_Open(fname, mode);
| Arguments | Description |
|---|---|
| fname | Name of the file(s) for the search (passed as a string). |
| mode | FILE_READ ('r'), FILE_WRITE ('w') or FILE_APPEND ('a') |
Returns: Handle if file exists. Sets internal file error number accordingly (0 if no errors).
Example
Note
- If a file is opened for write mode 'w', and the file already exists, the operation will fail. Unlike C and some other languages where the file will be erased ready for re-writing when opened for writing, 4DGL offers a simple level of protection that ensures that a file must be purposely erased before being re-written.
- Beginning with the v4.0 PmmC a file opened with FILE_APPEND may be randomly read and or written. Also any altered file will have the Archive bit set in the directory entry.
file_Read
Reads the number of bytes specified by size from the file referenced by handle into a destination memory buffer. Destination is always a word pointer, as you can only read into RAM which is word addressable. If destination is zero, data is read direct to GRAM window.
Syntax: file_Read(*destination, size, hanlde);
| Arguments | Description |
|---|---|
| destination | Destination memory buffer. This is a normal word aligned address. |
| size | Number of bytes to be read |
| handle | The handle that references the file to be read. |
Returns: Number of characters read.
Example
file_Seek
Places the file pointer at the required position in a file that has been opened in 'r' (read) or 'a' (append) mode. In append mode, file_Seek does not expand a filesize, instead, the file pointer (handle) is set to the end position of the file, e.g.:- assuming the file size is 10000 bytes, file_Seek(handle, 0, 0x1234); will set the file position to 0x00001234 (byte position 4660) for the file handle, so subsequent data may be read from that position onwards with file_GetC(...), file_GetW(...), file_GetS(...), or an image can be displayed with file_Image(...). Conversely, file_PutC(...), file_PutW(...) and file_PutS(...) can write to the file at the position. A FE_EOF (end of file error) will occur if you try to write or read past the end of the file.
Syntax: file_Seek(handle, HiWord, LoWord);
| Arguments | Description |
|---|---|
| handle | The handle that references the file |
| HiWord | Contains the upper 16bits of the memory pointer into the file |
| LoWord | Contains the lower 16bits of the memory pointer into the file |
Returns: TRUE if ok, usually ignored.
Example
file_Index
Places the file pointer at the position in a file that has been opened in 'r' (read) or 'a' (append) mode. In append mode, file_Index does not expand a filesize, instead, the file pointer (handle) is set to the end position of the file, e.g.:- assuming the record size is 100 bytes, file_Index(handle, 0, 100, 22); will set the file position to 2200 for the file handle, so subsequent data may be read from that position onwards with file_GetC(...), file_GetW(...), file_GetS(...), or an image can be displayed with file_Image(...). Conversely, file_PutC(...), file_PutW(...) and file_PutS(...) can write to the file at the position. A FE_EOF (end of file error) will occur if you try to write or read past the end of the file.
Syntax: file_Index(handle, Hisize, LoSize, recordnum);
| Arguments | Description |
|---|---|
| handle | The handle that references the file. |
| Hisize | Contains the upper 16bits of the size of the file records. |
| LoSize | Contains the lower 16bits of the size of the file records. |
| recordnum | The index of the required record. |
Returns: TRUE if ok, usually ignored.
Example:
file_Tell
Returns the current value of the file pointer.
Syntax: file_Tell(handle, &HiWord, &LoWord);
| Arguments | Description |
|---|---|
| handle | The handle that references the file. |
| HiWord | Contains the upper 16bits of the memory pointer into the file. |
| LoWord | Contains the lower 16bits of the memory pointer into the file. |
Returns: TRUE if ok, usually ignored.
Example:
file_Write
Writes the number of bytes specified by "size" from the source buffer into the file referenced by "handle".
Syntax: file_Write(*source, size, handle);
| Arguments | Description |
|---|---|
| source | Source memory buffer. This is a byte aligned string pointer. |
| size | Number of bytes to be written. |
| handle | The handle that references the file to write. |
Returns: The number of bytes written.
Example
file_Size
Reads the 32-bit file size and stores it into 2 variables.
Syntax: file_Size(handle, &HiWord, &LoWord);
| Arguments | Description |
|---|---|
| handle | The handle that references the file. |
| HiWord | Contains the upper 16bits of the file size. |
| LoWord | Contains the lower 16bits of the file size. |
Returns: TRUE if ok, usually ignored.
Example
file_Image
Display an image from the file stream at screen location specified by x, y(top left corner). If there is more than 1 image in the file, it can be accessed with file_Seek(...).
Syntax: file_Image(x, y, handle);
| Arguments | Description |
|---|---|
| x | X-position of the image to be displayed. |
| y | Y-position of the image to be displayed. |
| handle | The handle that references the file containing the image(s). |
Returns: A copy of the file_Error() error code
Example
file_ScreenCapture
Save an image of the screenshot to file at the current file position.
The image can later be displayed with file_Image(...);. The file may be opened in append mode to accumulate multiple images. Later, the images can be displayed with file_Seek(...).
The image is saved from x, y (with respect to top left corner), and the capture area is determined by "width" and "height".
Syntax: file_ScreenCapture(x, y, width, height, handle);
| Arguments | Description |
|---|---|
| x | X-position of the image to be captured. |
| y | Y-position of the image to be captured. |
| width | Width of the area to be captured. |
| height | Height of the area to be captured. |
| handle | The handle that references the file to store the image(s). |
Returns: Zero (0) if function successful.
Example
file_Mount();
hFile := file_Open("test.img", 'a'); // open a file to save the image
file_ScreenCapture(20,20,100,100, hFile);// save an area
file_ScreenCapture(0,0,50,50, hFile); // (save another area)
file_Close(hFile); // now close the file
// and to display the saved area(s)
hFile := file_Open("test.img", 'r'); // open the saved file
file_Image(20,180, hFile); // display the image
file_Image(150,180, hFile); // (display the next image)
file_Close(hFile);
file_Unmount(); // finished with file system
file_PutC
This function writes the byte specified by "char" to the file, at the position indicated by the associated file-position pointer and advances the pointer appropriately (incremented by 1). The file must be previously opened with 'w' (write) or 'a' (append) modes.
Syntax: file_PutC(char, handle);
| Arguments | Description |
|---|---|
| char | Data byte about to be written. |
| handle | The handle that references the file to be written to. |
Returns: The number of bytes written
Example
file_GetC
This function reads a byte from the file, at the position indicated by the associated file-position pointer and advances the pointer appropriately (incremented by 1). The file must be previously opened with 'r' (read) mode.
Syntax: file_GetC(handle);
| Arguments | Description |
|---|---|
| handle | The handle that reference the file. |
Returns: The data byte read from the file.
Example
file_PutW
This function writes word sized (2 bytes) data specified by "word" to the file, at the position indicated by the associated file-position pointer and advances the pointer appropriately (incremented by 2). The file must be previously opened with 'w' (write) or 'a' (append) modes.
Syntax: file_PutW(word, handle);
| Arguments | Description |
|---|---|
| word | Date about to be written. |
| handle | The handle that reference the file to be written to. |
Returns: The number of bytes written.
Example
file_GetW
This function reads a word (2 bytes) from the file, at the position indicated by the associated file-position pointer and advances the pointer appropriately (incremented by 2). The file must be previously opened with 'r' (read) mode.
Syntax: file_GetW(handle);
| Arguments | Description |
|---|---|
| handle | The handle that reference to the file. |
Returns: Word sized data read from the file..
Example
file_PutS
This function writes an ASCIIZ (null terminated) string from a buffer specified by "*source" to the file, at the position indicated by the associated file-position pointer and advances the pointer appropriately. The file must be previously opened with 'w' (write) or 'a' (append) modes.
Syntax: file_PutS(*source, handle);
| Arguments | Description |
|---|---|
| source | A pointer to the string to be written. |
| handle | The handle that references the file to be written to. |
Returns: The number of the characters written (excluding the null terminator).
Example
file_GetS
This function reads a line of text to a buffer (specified by "*string") from a file at the current file position indicated by the associated file-position pointer and advances the pointer appropriately.
file_GetS(...) will stop reading when any of the following conditions are true:
a. It has read n-1 bytes (one character is reserved for the null-terminator) b. It encounters a newline character (a line-feed in the compilers tested here) c. It reaches the end of file d. A read error occurs.
The file must be previously opened with 'r' (read) mode.
Syntax: file_GetS(*string, size, handle);
| Arguments | Description |
|---|---|
| string | Destination buffer. |
| size | The maximum number of bytes to be read from the file. |
| handle | The handle that references the file. |
Returns: The number of characters read from file (excluding the null terminator)
Example
file_Erase
This function erases a file on the disk.
Syntax: file_Erase(fname);
| Arguments | Description |
|---|---|
| fname | Name of the file to be erased. |
Returns: True (1) if successful, False (0) otherwise.
Example
Note
If the function fails, the approprialte error number is set in file_Error() and will usually be error 19, "failure during FILE search".
file_Rewind
Resets the file pointer to the beginning of a file that has been opened in 'r' (read), 'w', or 'a' (append) mode.
Syntax: file_Rewind(handle);
| Arguments | Description |
|---|---|
| handle | The handle that references the file. |
Returns: TRUE if ok, usually ignored.
Example
file_LoadFunction
Load a function or program from disk and return a function pointer to the allocation.
The function can then be invoked just like any other function would be called via a function pointer. Parameters may be passed to it in a conventional way. The function may be discarded at any time when no longer required, thus freeing its memory resources.
The loaded function can be discarded with mem_Free(..) Note that any pointer references passed to the child function may not include references to the parents DATA statements or any static string references. Any string or array information must be in the parents global or local memory space. The reason for this is that DATA statements and static strings are contained in the parents CODE segment, and cannot be accessed by the child process.
The callers stack is shared by the loaded function, however any global variables in the loaded function are private to that function.
Syntax: file_LoadFunction(fname.4XE);
| Arguments | Description |
|---|---|
| fname.4XE | Name of the 4DGL application program that is about to be loaded into RAM. |
Returns: A pointer to the memory allocation where the function has been loaded from file which can be then used as a function call.
Example
var titlestring[20];
var textstring[20];
to (titlestring); putstr("My Window Title");
to (textstring); putstr("My Special Message");
popupWindow := file_LoadFunction("popupWindow1.4fn");
if(!popupWindow) goto LoadFunctionFailed; // could not load the function
// then elsewhere in your program
res := popupWindow(MYMODE,titlestring,textstring);
if(res == QUIT_APPLICATION) goto exitApp;
// Later in your program, when popupWindow is no longer required
// for the application
res := mem_Free(popupWindow);
if(!res) goto FreeFunctionFailed; // should never happen if memory not
// corrupted
var fncHandle; // a var for a handle to sliders2.4dg
var slidervals; // reference var to access global vars in sliders.4dg
fncHandle := file_LoadFunction("sliders2.4xe"); // load the function
slidervals := fncHandle & 0x7FFF; // note that memory allocations
// for transient programs are biased with 8000h which must be removed.
slidervals++; // note that all globals start at '1'
slidervals[0] := 25; // set sliders to initial positions
slidervals[1] := 20;
slidervals[2] := 30;
slidervals[3] := 15;
slidervals[4] := 35;
slidervals[5] := 20;
slidervals[6] := 40;
slidervals[7] := 25;
slidervals[8] := 45;
slidervals[9] := 5;
r := fncHandle(); // activate the function
print("Return value = 0x", [HEX] r,"\n");
// print the values, they may have changed
print("Slider 1 ", slidervals[0]," Slider 2 ", slidervals[1],"\n");
print("Slider 3 ", slidervals[2]," Slider 4 ", slidervals[3],"\n");
print("Slider 5 ", slidervals[4]," Slider 6 ", slidervals[5],"\n");
print("Slider 7 ", slidervals[6]," Slider 8 ", slidervals[7],"\n");
print("Slider 9 ", slidervals[8]," Slider 10 ", slidervals[9],"\n");
mem_Free(fncHandle); // done with sliders, release its memory
Note
PmmC Rev 31 and above has an added feature where a parent can access the child global Variables when using file_LoadFunction(fname.4XE).
file_Run
Any memory allocations in the main FLASH program are released, however, the stack and globals are maintained.
If arglistptr is 0, no arguments are passed, else arglistptr points to an array, the first element containing the number of additional elements in the array which contain the arguments.
func 'main' in the called program accepts the arguments, if any.
The disk does not need to be mounted, file_Run automatically mounts the drive.
Syntax: file_Run(fname.4XE, arglistptr);
| Arguments | Description |
|---|---|
| fname.4XE | name of the 4DGL child program to be loaded into RAM and executed. |
| arglistptr | pointer to the list of arguments to pass to the new program. |
Returns: The value from main in the called program.
Example
#inherit "4DGL_16bitColours.fnc"
#inherit "FONT4.fnt"
#constant MAXBUTTONS 30 // for now, maximum number of buttons we want
// (also sets maximum number of files we can exec)
#STACK 500
//stack must be large enough to be shared with called program
#MODE RUNFLASH
// This is a 'top down' main program and must be run from FLASH
//-------------------------------------------------------------------// local global variables
//-------------------------------------------------------------------
// NB:- demo assigns all arrays to MAXBUTTONS.
// The arrays could be dynamically assigned to minimise memory usage.
// There is break even point between extra code and smallish arrays.
var keyval; // 0 if no key pressed else 1-n
var filenames; // pointer to byte array that holds the filenames
var buttontexts[MAXBUTTONS]; // pointers into the filenames array
//holds the filenames we use as button text
var vButtonState[MAXBUTTONS];
//button state flag( bit 0 = up:down state)
var vOldButtonState[MAXBUTTONS];
// OLD button state flags (bit 0 = up:down state)
// (we keep 2 copies so we can test for a state change and only redraw when a state change occurs)
var touchX1[MAXBUTTONS]; // touch regions for the buttons
var touchY1[MAXBUTTONS];
var touchX2[MAXBUTTONS];
var touchY2[MAXBUTTONS];
var btnTextColor; // button text colour
var btnBtnColor; // button background colour
var buttoncount; // actual number of buttons created (set by number of *.4XE files we find on drive)
var tempstr[20]; // general purpose string, 40 bytes
#DATA
byte fred 1,2,3,4,5,6,7,8,9,10,11,12
#END
/*===================================================================
Redraw the button matrix. Only draw buttons that have changed state.
The top lef corner of the button matrix is set with the xorg and yorg parameters depending on the font and text string width, the button matrix dynamically resizes.
Parameters:-
maxwidth = rhs from xorg (in pixels) to cause wrap at rhs
maxwidth = maximum matrix width (in pixel units)
buttoncount = number of buttons to display
font = FONT1 to FONT4
xorg:yorg = top left corner of button array
NB:- The touch detect matrix array is updated when any button changes state.
When you need to draw the matrix for the first instance of the matrix, you must
call with mode = 1 to instantiate the buttons.
call with mode = 0 for normal button action.
===================================================================*/
func redraw(var bcount, var font, var xorg, var yorg, var maxwidth, var mode )
var xgap, ygap, n, x1, y1, x2, y2;
xgap := 2;
ygap := 2;
x1 := xorg;
y1 := yorg;
// if first, set all the buttons to the up state
if (mode)
n := 0;
repeat
vButtonState[n]:=UP;
// set all the buttons to inverse state
vOldButtonState[n]:=DOWN;
// so we guarantee they are all drawn in the 'up' state (not pressed)
until(++n >= buttoncount);
endif
// check all the button states, if a change occured, draw the new button state and update the touch detect matrix array
n := 0;
repeat
// if the button state has changed
if ( vButtonState[n] != vOldButtonState[n])
vOldButtonState[n] := vButtonState[n];
// if we already have all the co-ordinates, use them
if (!mode)
x1 := touchX1[n];
y1 := touchY1[n];
x2 := touchX2[n];
y2 := touchY2[n];
endif
// draw the button
gfx_Button( vButtonState[n], x1, y1, btnBtnColor, btnTextColor, font, 1, 1, buttontexts[n] );
// update the touch screen regions only during first build
if (mode)
x2 := gfx_Get(RIGHT_POS);
y2 := gfx_Get(BOTTOM_POS);
touchX1[n] := x1;
touchY1[n] := y1;
touchX2[n] := x2;
touchY2[n] := y2;
// calculate next button position
x1 := x2 + xgap;
if (x1 >= xorg + maxwidth)
x1 := xorg;
y1 := y2 + ygap;
endif
endif
endif
until (++n >= buttoncount);
endfunc
//===================================================================
// do something with the key data
// In this example, we reconstitute the button name to a file name
// by appending ".4XE" and then call the file_Run command to
// run an application.
//===================================================================
func sendkey()
var p;
p := buttontexts[keyval-1];
to(tempstr); str_Printf(&p, "%s.4XE");
txt_Set(TEXT_OPACITY, OPAQUE);
txt_Set(FONT_ID , FONT4);
txt_MoveCursor(3, 0);
print (" ");
if(file_Exists(str_Ptr(tempstr)))
touch_Set(TOUCH_DISABLE); // disable the touch screen
txt_Set(TEXT_COLOUR, ORANGE);
print ("\rRUN: ", [STR] tempstr );// run the required program
pause(500);
gfx_Cls();
file_Run(str_Ptr(tempstr),0); // just run the prog, no args
else
txt_Set(TEXT_COLOUR, RED);
print ("\rFAULT: ", [STR] tempstr ); // run required program
pause(1000);
endif
endfunc
//===================================================================
// convert the touch co-ordinates to a key value
// returns 0 if no key down else return index 1..n of button
//===================================================================
func readKeys(var x, var y)
var n, x1, y1, x2, y2, r;
n := 0;
r := 0;
while (n < buttoncount && !r)
x1 := touchX1[n];
y1 := touchY1[n];
x2 := touchX2[n];
y2 := touchY2[n];
n++;
if (x >= x1 && x < x2 && y >= y1 && y < y2) r := n;
wend
return r;
endfunc
//==================================================================
func main()
var k, n, state, x, y;
var p, s, w, f;
redo:
w := 140;
f := FONT4;
btnTextColor := BLACK;
btnBtnColor := LIGHTGREY;
gfx_Cls();
gfx_Set(BEVEL_WIDTH, 2);
txt_Set(FONT_ID, FONT3);
print("Simple test for file_Run(...);\n");
print("Memory available = ",mem_Heap(),"\n");
if(!file_Mount())
putstr("Disk not mounted");
while(!file_Mount());
else
putstr("Disk mounted\n");
endif
buttoncount := file_Count("*.4xe");
// count all the executable files on the drive
print("4XE File count = ",buttoncount,"\n");
n := buttoncount; // k holds entry count
if (!n)
print("No 4XE executables\n");
// critical error, nothing to run!
repeat forever
endif
filenames := mem_AllocZ(n*13);
// allocate a buffer for the filenames
if(!filenames)
print("Out of memory\n");
// critical error, could not allocate buffer
repeat forever
endif
to(filenames); file_Dir("*.4xe");
// load the filenames array
p := str_Ptr(filenames); // point to the string
//assign array of string pointers and truncate filename extensions
n := 0;
while ( n < buttoncount )
buttontexts[n++] := p; // save pointer to the string
p:=str_Find ( &p , "." ); // find end of required string
str_PutByte(p++,'\0'); // change '.' to \0
p := p + 4; // skip over "4XE\n"
wend
touch_Set(TOUCH_ENABLE); // enable the touch screen
redraw(buttoncount, f, 10, 80, w, 1);
// draw buttons for the first time
// now just stay in a loop
repeat
state := touch_Get(TOUCH_STATUS); // get touchscreen status
x := touch_Get(TOUCH_GETX);
y := touch_Get(TOUCH_GETY);
if(state == TOUCH_PRESSED) // if there's a press
if (keyval := readKeys(x, y))
vButtonState[keyval-1] := DOWN;
// put button in DOWN state
redraw(buttoncount, f, 10, 80, w, 0);
// draw any button down states
endif
endif
if(state == TOUCH_RELEASED)
// if there's a release
if (keyval)
vButtonState[keyval-1] := UP;
// restore the buttons UP state
redraw(buttoncount, f, 10, 80, w, 0);
// draw any button up states
sendkey();
// do something with the key data
keyval := 0;
// because prog(main prog) gave up all its allocations for file_Exec,
// we have lost our file mount info and the directory list so we must
// re-establish these to be able to continue. A better approach to
// ensure total stability for the main program is to reset the system
// with SystemReset()
//==================================
// systemReset() // restart the main program
// or
goto redo; // re-mount disk, reload filenames
//==================================
endif
endif
forever
// mem_Free(filenames);
// no need to release buffer, this prog is in flash and never exits.....
// file_Unmount(); // ditto
endfunc
//===================================================================
file_Exec
This function is similar to file_Run, however, the main program in FLASH retains all memory allocations (e.g. file buffers, memory allocated with mem_Alloc etc).
Syntax: file_Exec(fname.4XE, arglistptr);
| Arguments | Description |
|---|---|
| fname | Name of the 4DGL child program to be loaded into RAM and executed. |
| arglistptr | Pointer to the list of arguments to pass to the new program or 0 if no arguments. |
Returns: The value from main in the called program.
Example
var args[4], l[50] ;
func main()
var i ;
putstr("Mounting...\n"); // must mount uSD for file_Exec
if (!(file_Mount()))
while(!(file_Mount()))
putstr("Drive not mounted...");
pause(200);
gfx_Cls();
pause(200);
wend
endif
for (i := 0; i < sizeof(l); i++) // init array that will be passed
l[i] := i ;
next
args[0] := 2 ; // init arg count
args[1] := 1234 ; // init arg 1, this cannot be changed
args[2] := l ; // init arg 2 to address of l
print("main Program\n" ) ;
i := file_Exec("uSDProg.4fn", args) ;
print("Back in main program\n" ) ;
print("uSD Program returned ", i, "\n") ; // number from return statement
for (i := 0; i < sizeof(l); i++) // find what changed in array
if (l[i] != i) print("l[", i, "] was changed to ", l[i], "\n" ) ;
next
print("Done") ;
repeat
forever
endfunc
func main(var j, var *l) // parameters appear in the normal way
// The * shows that l will be indexed. It
// simply stops the compiler issuing a 'notice'
txt_FGcolour(WHITE);
print("In file_Exec's Program\n") ;
print("Parms=", j, " ", l, "(ptr to l)\n") ; // can't change these
print("Incrementing l[5] to ", ++l[5], "\n") ; // can change these
print("Returning 188\n") ; // can return a value
txt_FGcolour(LIME);
return 188;
endfunc
file_LoadImageControl
Reads a control file to create an image list.
The following are the modes of operation
| Mode | Description |
|---|---|
| 0 | It is assumed that there is a graphics file with the file extension "fname2.gci". In this case, the images have been stored in a FAT16 file concurrently, and the offsets that are derived from the "fname1.dat" file are saved in the image control so that the image control can open the file (.gci) and use file_Seek(...) to get to the position of the image which can then automatically be displayed using file_Image(...). Mode 0 builds the image control quickly as it only scans the .dat file for the file offsets and saves them in the relevant entries in the image control. The penalty is that images take longer to find when displayed due to file_Seek(...) overheads. |
| 1 | It is assumed that there is a graphics file with the file extension "fname2.gci". In this case, the images have been stored in a FAT16 file concurrently, and the offset of the images are saved in the image control so that image file (*.gci) can be mapped to directly. The absolute cluster/sector is mapped so file seek does not need to be called internally. This means that there is no seek time penalty, however, the image list takes a lot longer to build, as all the seeking is done at control build time. |
| 2 | In this case, the images have been stored in a in a RAW partition of the uSD card, and the absolute address of the images are saved in the DAT file. This is the fastest operation of the image control as there is no seeking or other disk activity taking place. |
When an image control is loaded, an array is built in RAM. It consists of a 6 word header with the following entries as defined by the constants:
| Information | Index |
|---|---|
| IMG_COUNT | 0 |
| IMG_ENTRYLEN | 1 |
| IMG_MODE | 2 |
| IMG_GCI_FILENAME | 3 |
| IMG_DAT_FILENAME | 4 |
| IMG_GCIFILE_HANDLE | 5 |
No images are stored in FLASH or RAM, the image control holds the index values for the absolute storage positions on the uSD card for RAW mode, or the cluster/sector position for formatted FAT16 mode.
When an image control is no longer required, the memory can be released with mem_Free();
Syntax: file_LoadImageControl(fname1, fname2, mode);
| Argument | Description |
|---|---|
| fname1 | The control list filename "*.dat". Created from Graphics Composer. |
| fname2 | The image filename "*.gci". Created from Graphics Composer. |
| mode | Determines the mode of operation |
Return: Pointer (handle) to the memory allocation to the image control list that has been created, null (0) if function fails
Example
#inherit "4DGL_16bitColours.fnc"
#constant OK 1
#constant FAIL 0
var p; // buffer pointer
var img; // handle for the image list
var n, exit, r;
//-------------------------------------------------------------------
// return true if screen touched, also sets ok flag
func CheckTouchExit()
return (exit := (touch_Get(TOUCH_STATUS) == TOUCH_PRESSED)); // if there's a press, exit
endfunc
//-------------------------------------------------------------------
func main()
gfx_Cls();
txt_Set(FONT_ID, FONT2);
txt_Set(TEXT_OPACITY, OPAQUE);
touch_Set(TOUCH_ENABLE); // enable the touch screen
print("heap=", mem_Heap(), " bytes\n"); // show the heap size
r := OK; // return value
exit := 0;
if (!file_Mount())
print("File error ", file_Error());
while(!CheckTouchExit());
// just hang if we didnt get the image list
r := FAIL;
goto quit;
endif
print ("WAIT...building image list\n");
// slow build, fast execution, higher memory requirement
img := file_LoadImageControl("GFX2DEMO.dat", "GFX2DEMO.gci", 1);
// build image control, returning a pointer to structure allocation
if (img)
print("image control=",[HEX] img,"\n");
// show the address of the image control allocation
else
putstr("Failed to build image control....\n");
while(CheckTouchExit() == 0);
// just hang if we didnt get the image list
r := FAIL;
goto quit;
endif
print ("Loaded ", img[IMG_COUNT], " images\n");
print ("\nTouch and hold to exit...\n");
pause(2000);
pause(3000);
gfx_Cls();
repeat
n := 0;
while(n < img[IMG_COUNT] && !exit) // go through all images
CheckTouchExit(); // if there's a press, exit
img_SetPosition( img, n, (ABS(RAND() % 240)), (ABS(RAND() % 320))); // spread out the images
n++;
wend
img_Show(img, ALL); // update the entire control in 1 hit
until(exit);
quit:
mem_Free(img); // release the image control
file_Unmount(); // (program must release all resources)
return r;
endfunc
//===================================================================
file_Mount
Starts up the FAT16 disk file services and allocates a small 32 byte control block for subsequent use. When you open a file using file_Open(...), a further 512 + 44 = 556 bytes are attached to the FAT16 file control block. When you close a file using file_Close(...), the 556 byte allocation is released leaving the 32 byte file control block. The file_Mount() function must be called before any other FAT16 file related functions can be used. The control block and all FAT16 file resources are completely released with file_Unmount().
Syntax: file_Mount();
Return: True (1) if successful, False (0) otherwise
Example
if( !file_Mount() )
repeat
putstr("Disk not mounted");
pause(200);
gfx_Cls();
pause(200);
until( file_Mount() );
endif
file_Unmount
Release any buffers for FAT16 and unmount the Disk File System. This function is to be called to close the FAT16 file system.
Syntax: file_Unmount();
Return: None
Example
file_PlayWAV
Open the wav file, decode the header to set the appropriate wave player parameters and set off the playing of the file as a background process. See Sound Control Functions for additional play control functions.
This function may return the following values if unsuccessful:
| Value | Error Description |
|---|---|
| -7 | Insufficient memory available for WAV buffer and file |
| -6 | cant play this rate |
| -5 | no data chunk found in first rsector |
| -4 | no format data |
| -3 | no wave chunk signature |
| -2 | bad wave file format |
| -1 | file not found |
Syntax: file_PlayWAV(fname);
| Argument | Description |
|---|---|
| fname | Filename of the wav file to be opened and played |
Return: Number of blocks to play (1 to 32767), or error code otherwise.
Example
print("\nding.wav\n");
for (n := 0; n < 45; n++)
pitch := NOTES[n];
print([UDEC] pitch,"\r");
snd_Pitch(pitch);
file_PlayWAV("ding.wav");
while(snd_Playing());
//pause(500);
next
Flash Memory Functions
The functions in this section only apply to serial SPI (NAND) flash devices interfaced to the Picaso SPI port.
flash_SIG
If a FLASH storage device is connected to the SPI port, and has been correctly initialised with the spi_Init(...) function, the Electronic Signature of the device can be read using this function. The only devices supported so far on the Picaso are the M25Pxx range of devices which are 512Kbit to 32Mbit (2M x 8) Serial Flash Memory.
Syntax: flash_SIG();
Returns: Release from Deep Power-down, and Read Electronic Signature. Only the low order byte is valid, the upper byte is ignored.
Example:
var sig, id;
spi_Init(SPI_SLOW, RXMODE_0, CKMODE_0);
//...
sig := flash_SIG();
id := flash_ID();
print("Flash Signature:", [HEX4] sig, "\n") ;
print("Flash (JEDEC)ID:", [HEX4] id, "\n") ;
flash_ID
If a FLASH storage device is connected to the SPI port, and has been correctly initialised with the spi_Init(...) function, the memory type and capacity from the flash device can be read using this function. The only devices supported so far on the Picaso are the M25Pxx range of devices which are 512Kbit to 32Mbit (2M x 8) Serial Flash Memory.
Syntax: flash_ID();
Returns: Reads the memory type and capacity from the serial FLASH device. Hi byte contains type, and low byte contains capacity. Refer to the device data sheet for further information.
Example
Refer to the example under the flash_SIG() section.
flash_BulkErase
If a FLASH storage device is connected to the SPI port, and has been correctly initialised with the spi_Init(...) function, the FLASH device can be completely erased using this function. The only devices supported so far on the Picaso are the M25Pxx range of devices which are 512Kbit to 32Mbit (2M x 8) Serial Flash Memory.
Syntax: flash_BulkErase();
Returns: None
Note
Erases the entire flash media device. The function returns no value, and the operation can take up to 80 seconds depending on the size of the flash device.
flash_BlockErase
If a FLASH storage device is connected to the SPI port, and has been correctly initialised with the spi_Init(...) function, the FLASH block can be erased using this function. The only devices supported so far on the Picaso are the M25Pxx range of devices which are 512Kbit to 32Mbit (2M x 8) Serial Flash Memory. E.g. there are 32 x 64K blocks on a 2Mb flash device.
Syntax: flash_BlockErase(blockAddress);
| Arguments | Description |
|---|---|
| blockAddress | The address of the 64k FLASH block to be erased. |
Returns: None
Note
Erases the required block in a FLASH media device. The function returns no value, and the operation can take up to 3 milliseconds.
General Purpose Functions
pause
Stop execution of the user program for a predetermined amount of time.
Syntax: pause(time);
| Arguments | Description |
|---|---|
| time | A value specifying the delay time in milliseconds. |
Returns: None
Example
lookup8
Search a list of 8-bit constant values for a match with a search value key. If found, the index of the matching constant is returned in result, else result is set to zero. Thus, if the value is found first in the list, result is set to one. If second in the list, result is set to two etc. If not found, result is returned with zero.
Syntax: lookup8(key, byteConstList);
| Arguments | Description |
|---|---|
| key | A byte value to search for in a fixed list of constants. The key argument can be a variable, array element, expression or constant. |
| byteConstList | A comma separated list of constants and strings to be matched against key. |
Returns: The index of the matching constant, otherwise zero.
Example
func main()
var key, r;
key := 'a';
r := lookup8(key, 0x4D, "abcd", 2, 'Z', 5);
print(" nSearch value 'a' \nfound as index ", r)
key := 5;
r := lookup8(key, 0x4D, "abcd", 2, 'Z', 5);
print("\nSearch value 5 \nfound at index ", r)
putstr("\nScanning..\n");
key := -12000; // we will count from 12000 to +12000, only
// the hex ascii values will give a match value
while(key <= 12000)
r := lookup8(key, "0123456789ABCDEF" ); // hex lookup
if(r) print([HEX1] r 1); // only print if we got a match in
// the table
key++;
wend
repeat forever
endfunc
Note
The list of constants cannot be re-directed. The lookup8(...) function offer a versatile way for returning an index for a given value. This can be very useful for data entry filtering and parameter input checking and where ever you need to check the validity of certain inputs. The entire search list field can be replaced with a single name if you use the $ operator in constant, e.g. :
#constant HEXVALUES $"0123456789ABCDEF"
lookup16
Search a list of 16-bit constant values for a match with a search value key. If found, the index of the matching constant is returned in result, else result is set to zero. Thus, if the value is found first in the list, result is set to one. If second in the list, result is set to two etc. If not found, result is returned with zero.
| Arguments | Description |
|---|---|
| key | A byte value to search for in a fixed list of constants. The key argument can be a variable, array element, expression or constant. |
| wordConstList | A comma separated list of constants to be matched against key. |
Returns: The index of the matching constant, otherwise zero
Example
func main()
var key, r;
key := 5000;
r := lookup16(key, 5,10,20,50,100,200,500,1000,2000,5000,10000);
//r := lookup16(key,
if(r)
print("\nSearch value 5000 \nfound at index ", r);
else
putstr("\nValue not found");
endif
print("\nOk"); // all done
repeat forever
endfunc
Note
The lookup16(...) function offer a versatile way for returning an index for a given value. This is very useful for parameter input checking and where ever you need to check the validity of certain values. The entire search list field can be replaced with a single name by using the $ operator in constant, e.g.:
#constant LEGALVALS $5,10,20,50,100,200,500,1000,2000,5000,10000
GPIO Functions
pin_Set
Picaso has limited but powerful I/O.
There are pre-defined constants for mode and pin:
| Pin Constants | Pin number on the Picaso chip | Remarks |
|---|---|---|
| IO1_PIN | pin 1 | |
| IO2_PIN | pin 64 | |
| IO3_PIN | pin 63 | |
| IO4_PIN | pin 62 | also used for BUS_RD |
| IO5_PIN | pin 44 | also used for BUS_WR |
| BACKLITE | Backlight control pin | Used internally. Permanently set as Output. HIGH: BACKLITE ON LOW : BACKLITE OFF |
| AUDIO_ENABLE | Amplifier Chip control pin | Used internally. Permanently set as Output. HIGH: Amplifier OFF LOW : Amplifier ON |
| mode constants | mode value | meaning | IO1 | IO2 | IO3 | IO4 | IO5 |
|---|---|---|---|---|---|---|---|
| OUTPUT | 0 | Pin is set to an output | YES | YES | YES | YES | YES |
| INPUT | 1 | Pin is set to an input | YES | YES | YES | YES | YES |
Syntax: pin_Set(mode, pin);
| Arguments | Description |
|---|---|
| mode | A value (usually a constant) specifying the pin operation. |
| pin | A value (usually a constant) specifying the pin number. |
Returns: None
Example
pin_Set(OUTPUT, IO2_PIN); // set IO2 to be used as an output
pin_Set(INPUT, IO1_PIN); // set IO1 to be used as an input
Note
If using PIN_AN or PIN_ANAVG via the pin_Read() function, then if Touch is enabled this function should be called no more than once per millisecond, otherwise touch behaviour could be erratic.
pin_HI
Outputs a "High" level (logic 1) on the appropriate pin that was previously selected as an Output. If the pin is not already set to an output, it is automatically made an output.
Syntax: pin_HI(pin);
| Arguments | Description |
|---|---|
| pin | A value (usually a constant) specifying the pin number . |
Returns: None.
Example
pin_LO
Outputs a "Low" level (logic 0) on the appropriate pin that was previously selected as an Output. If the pin is not already set to an output, it is automatically made an output.
Syntax: pin_LO(pin);
| Arguments | Description |
|---|---|
| pin | A value (usually a constant) specifying the pin number. |
Returns: None.
Example
pin_Read
Reads the logic state of the pin that was previously selected as an Input. Returns a "Low" (logic 0) or "High" (logic 1).
Syntax: pin_Read(pin);
| Arguments | Description |
|---|---|
| pin | A value (usually a constant) specifying the pin number. |
Returns: A Logic 1 (0x0001) or a Logic 0 (0x0000) or the analogue value of the input pin.
Example
bus_In
Returns the state of the bus as an 8bit value in to the lower byte of the assigned variable.
Note
The BUS_RD and BUS_WR pins are not affected.
Syntax: bus_In();
Returns: The state of the bus as a 8bit value.
Example
bus_Out
The lower byte of the argument is placed on the 8bit wide bus. The upper byte of the argument is ignored.
Note
The BUS_RD and BUS_WR pins are not affected. Any BUS pins that are set to inputs are not affected.
Syntax: bus_Out(arg1);
| Arguments | Description |
|---|---|
| arg | A value (usually a constant) specifying the pin number. |
Returns: None.
Example
bus_Set
The lower 8 bits of arg1 are placed in the BUS direction register.
A '1' sets a pin to be an input, a '0' sets a pin to be output.
The upper 8 bits of arg1 are ignored. The BUS_RD and BUS_WR pins are not affected.
Syntax: bus_Set(arg1);
| Arguments | Description |
|---|---|
| arg | A value (usually a constant) specifying the pin number. |
Returns: None.
Example
bus_Read
Returns the state of the bus as a 8bit value in to the lower byte of the assigned variable.
Note
The BUS_RD and BUS_WR pins are not affected. The BUS_RD pin set to LO, then, after a settling delay of approx 50nsec, the BUS is read into the lower 8 bits of the assigned variable (the upper 8 bits being set to 0) the BUS_RD pin is then set back to a HI level. The BUS_RD pin is automatically pre-set to an output to ensure BUS write integrity.
Syntax: bus_Read();
Returns: The state of the bus as a 8bit value.
Example
bus_Write
The lower 8 bits of arg1 are placed on the BUS, then, after a settling delay of approx 50nsec, the BUS_WR pin is strobed LO for approx 50nsec then set back HI. The upper 8 bits of arg1 are ignored.
Note
The BUS_WR pin is automatically pre-set to an output to ensure BUS write integrity.
Syntax: bus_Write(data);
| Arguments | Description |
|---|---|
| data | The lower 8-bits of data are sent to the bus. |
Returns: None
Example
Graphics Functions
gfx_Cls
Clear the screen using the current background colour. gfx_Cls() command brings some of the settings back to default; such as,
- Transparency turned OFF
- Outline colour set to BLACK
- Opacity set to OPAQUE
- Pen set to OUTLINE
- Line patterns set to OFF
- Right text margin set to full width
- Text magnifications set to 1
- All origins set to 0:0
The alternative to maintain settings and clear screen is to draw a filled rectangle with the required background colour.
Syntax: gfx_Cls();
Returns: None
Example
gfx_ChangeColour
Changes all oldColour pixels to newColour within the clipping area.
Syntax: gfx_ChangeColour(oldColour, newColour);
| Arguments | Description |
|---|---|
| oldColour | Specifies the sample colour to be changed within the clipping window. |
| newColour | Specifies the new colour to change all occurrences of old colour within the clipping window. |
Returns: None
Example
func main()
txt_Width(3);
txt_Height(5);
gfx_MoveTo(8,20);
print("TEST"); // print the string
gfx_SetClipRegion(); // force clipping area to extents of text
// just printed
gfx_ChangeColour(BLACK, RED); // test change of background colour
repeat forever
endfunc
// This example prints a test string, forces the clipping area to the extent of the text that was printed then changes the background colour.
gfx_Circle
Draws a circle with centre point x1, y1 with radius r using the specified colour.
Syntax: gfx_Circle(x, y, rad, colour);
| Arguments | Description |
|---|---|
| x,y | Specifies the centre of the circle. |
| rad | Specifies the radius of the circle. |
| colour | Specifies the colour of the circle. |
Returns: None
Example
// assuming PEN_SIZE is OUTLINE
gfx_Circle(50,50,30, RED);
// This example draws a BLUE circle outline centred at x=50, y=50 with a radius of 30 pixel units.
Note
The default PEN_SIZE is set to OUTLINE, however, if PEN_SIZE is set to SOLID, the circle will be drawn filled, if PEN_SIZE is set to OUTLINE, the circle will be drawn as an outline. If the circle is drawn as SOLID, the outline colour can be specified with gfx_OutlineColour(...). If OUTLINE_COLOUR is set to 0, no outline is drawn.
gfx_CircleFilled
Draws a SOLID circle with centre point x1, y1 with radius using the specified colour.
The outline colour can be specified with gfx_OutlineColour(...). If OUTLINE_COLOUR is set to 0, no outline is drawn.
Syntax: gfx_CircleFilled(x, y, rad, colour);
| Arguments | Description |
|---|---|
| x,y | Specifies the centre of the circle. |
| rad | Specifies the radius of the circle. |
| colour | Specifies the fill colour of the circle. |
Returns: None
Example
if(state == TOUCH_RELEASED) // if there's a release;
gfx_CircleFilled(x, y, 10, RED); // we'll draw a solid red circle
// of radius=10 on touch release
endif
Note
The PEN_SIZE is ignored, the circle is always drawn SOLID.
gfx_Line
Draws a line from x1, y1 to x2, y2 using the specified colour. The line is drawn using the current object colour. The current origin is not altered. The line may be tessellated with the gfx_LinePattern(...) function.
Syntax: gfx_Line(x1, y1, x2, y2, colour);
| Arguments | Description |
|---|---|
| x1, y1 | Specifies the starting coordinates of the line. |
| x2, y2 | Specifies the ending coordinates of the line. |
| colour | Specifies the colour of the line. |
Returns: None
Example
gfx_Line(100, 100, 10, 10, RED);
// This example draws a RED line from x1=10, y1=10 to x2=100, y2=100
gfx_Hline
Draws a fast horizontal line from x1 to x2 at vertical co-ordinate y using colour.
Syntax: gfx_Hline(y, x1, x2, colour);
| Arguments | Description |
|---|---|
| y | Specifies the vertical position of the horizontal line. |
| x1, x2 | Specifies the horizontal end points of the line. |
| colour | Specifies the colour of the horizontal line. |
Returns: None
Example
gfx_Hline(50, 10, 80, RED);
// This example draws a fast RED horizontal line at y=50, from x1=10 to x2=80
gfx_Vline
Draws a fast vertical line from y1 to y2 at horizontal co-ordinate x using colour.
Syntax: gfx_Vline(x, y1, y2, colour);
| Arguments | Description |
|---|---|
| x | Specifies the horizontal position of the vertical line. |
| y1, y2 | Specifies the vertical end points of the line. |
| colour | Specifies the colour of the vertical line. |
Returns: None
Example
gfx_Vline(20, 30, 70, RED);
// This example draws a fast RED vertical line at x=20, from y1=30 to y2=70
gfx_Rectangle
Draws a rectangle from x1, y1 to x2, y2 using the specified colour. The line may be tessellated with the gfx_LinePattern(...) function.
Syntax: gfx_Rectangle(x1, y1, x2, y2, colour);
| Arguments | Description |
|---|---|
| x1, y1 | Specifies the top left corner of the rectangle. |
| x2, y2 | Specifies the bottom right corner of the rectangle. |
| colour | Specifies the colour of the rectangle. |
Returns: None
Example
gfx_Rectangle(10, 10, 30, 30, GREEN);
// This example draws a GREEN rectangle from x1=10, y1=10 to x2=30, y2=30
Note
The default PEN_SIZE is set to OUTLINE, however, if PEN_SIZE is set to SOLID, the rectangle will be drawn filled, if PEN_SIZE is set to OUTLINE, the rectangle will be drawn as an outline. If the rectangle is drawn as SOLID, the outline colour can be specified with gfx_OutlineColour(...). If OUTLINE_COLOUR is set to 0, no outline is drawn. The outline may be tessellated with the gfx_LinePattern(...) function.
gfx_RectangleFilled
Draws a SOLID rectangle from x1, y1 to x2, y2 using the specified colour. The line may be tessellated with the gfx_LinePattern(...) function.
The outline colour can be specified with gfx_OutlineColour(...). If OUTLINE_COLOUR is set to 0, no outline is drawn. The outline may be tessellated with the gfx_LinePattern(...) function.
Syntax: gfx_RectangleFilled(x1, y1, x2, y2, colour);
| Arguments | Description |
|---|---|
| x1, y1 | Specifies the top left corner of the rectangle. |
| x2, y2 | Specifies the bottom right corner of the rectangle. |
| colour | Specifies the fill colour of the rectangle. |
Returns: None
Example
gfx_RectangleFilled(30,30,80,80, RED);
// This example draws a filled RED rectangle from x1=30,y1=30 to x2=80,y2=80
Note
The PEN_SIZE is ignored, the rectangle is always drawn SOLID.
gfx_Polyline
Plots lines between points specified by a pair of arrays using the specified colour. The lines may be tessellated with the gfx_LinePattern(...) function. gfx_Polyline can be used to create complex raster graphics by loading the arrays from serial input or from MEDIA with very little code requirement.
Syntax: gfx_Polyline(n, vx, vy, colour);
| Arguments | Description |
|---|---|
| n | Specifies the number of elements in the x and y arrays specifying the vertices for the polyline. |
| vx | Specifies the addresses of the storage of the array of elements for the x coordinates of the vertices. |
| vy | Specifies the addresses of the storage of the array of elements for the y coordinates of the vertices. |
| colour | Specifies the colour for the lines. |
Returns: None
Example
#inherit "4DGL_16bitColours.fnc"
var vx[20], vy[20];
func main()
vx[0] := 36; vy[0] := 110;
vx[1] := 36; vy[1] := 80;
vx[2] := 50; vy[2] := 80;
vx[3] := 50; vy[3] := 110;
vx[4] := 76; vy[4] := 104;
vx[5] := 85; vy[5] := 80;
vx[6] := 94; vy[6] := 104;
vx[7] := 76; vy[7] := 70;
vx[8] := 85; vy[8] := 76;
vx[9] := 94; vy[9] := 70;
vx[10] := 110; vy[10] := 66;
vx[11] := 110; vy[11] := 80;
vx[12] := 100; vy[12] := 90;
vx[13] := 120; vy[13] := 90;
vx[14] := 110; vy[14] := 80;
vx[15] := 101; vy[15] := 70;
vx[16] := 110; vy[16] := 76;
vx[17] := 119; vy[17] := 70;
// house
gfx_Rectangle(6,50,66,110,RED); // frame
gfx_Triangle(6,50,36,9,66,50,YELLOW); // roof
gfx_Polyline(4, vx, vy, CYAN); // door
// man
gfx_Circle(85, 56, 10, BLUE); // head
gfx_Line(85, 66, 85, 80, BLUE); // body
gfx_Polyline(3, vx+4, vy+4, CYAN); // legs
gfx_Polyline(3, vx+7, vy+7, BLUE); // arms
// woman
gfx_Circle(110, 56, 10, PINK); // head
gfx_Polyline(5, vx+10, vy+10, BROWN); // dress
gfx_Line(104, 104, 106, 90, PINK); // left arm
gfx_Line(112, 90, 116, 104, PINK); // right arm
gfx_Polyline(3, vx+15, vy+15, SALMON); // dress
repeat forever
endfunc
// This example draws a simple scene
gfx_Polygon
Plots lines between points specified by a pair of arrays using the specified colour. The last point is drawn back to the first point, completing the polygon. The lines may be tessellated with the gfx_LinePattern(...) function. gfx_Polygon can be used to create complex raster graphics by loading the arrays from serial input or from MEDIA with very little code requirement.
Syntax: gfx_Polygon(n, vx, vy, colour);
| Arguments | Description |
|---|---|
| n | Specifies the number of elements in the x and y arrays specifying the vertices for the polygon. |
| vx | Specifies the addresses of the storage of the array of elements for the x coordinates of the vertices. |
| vy | Specifies the addresses of the storage of the array of elements for the y coordinates of the vertices. |
| colour | Specifies the colour for the polygon. |
Returns: None
Example
var vx[7], vy[7];
func main()
vx[0] := 10; vy[0] := 10;
vx[1] := 35; vy[1] := 5;
vx[2] := 80; vy[2] := 10;
vx[3] := 60; vy[3] := 25;
vx[4] := 80; vy[4] := 40;
vx[5] := 35; vy[5] := 50;
vx[6] := 10; vy[6] := 40;
gfx_Polygon(7, vx, vy, RED);
repeat forever
endfunc
// This example draws a simple polygon
gfx_Triangle
Draws a triangle outline between vertices x1,y1 , x2,y2 and x3,y3 using the specified colour. The line may be tessellated with the gfx_LinePattern(...) function. Vertices must be specified in an anti-clockwise fashion.
Syntax: gfx_Triangle(x1, y1, x2, y2, x3, y3, colour);
| Arguments | Description |
|---|---|
| x1, y1 | Specifies the first vertices of the triangle. |
| x2, y2 | Specifies the second vertices of the triangle. |
| x3, y3 | Specifies the third vertices of the triangle. |
| colour | Specifies the colour for the triangle. |
Returns: None
Example
gfx_Triangle(10,10,30,10,20,30,CYAN);
// This example draws a CYAN triangular outline with vertices at 10,10 30,10 20,30
gfx_Dot
Draws a pixel at the current origin using the current object colour.
Syntax: gfx_Dot();
Returns: None
Example
gfx_Bullet
Draws a circle or 'bullet point' with radius r at the current origin using the current object colour.
Syntax: gfx_Bullet(radius);
| Arguments | Description |
|---|---|
| radius | Specifies the radius of the bullet. |
Returns: None
Example
Note
The default PEN_SIZE is set to OUTLINE, however, if PEN_SIZE is set to SOLID, the circle will be drawn filled, if PEN_SIZE is set to OUTLINE, the circle will be drawn as an outline. If the circle is drawn as SOLID, the outline colour can be specified with gfx_OutlineColour(...).
gfx_OrbitInit
Sets up the internal pointers for the gfx_Orbit(..) result variables. The &x_orb and &y_orb parameters are the addresses of the variables or array elements that are used to store the result from the gfx_Orbit(..) function.
Syntax: gfx_OrbitInit(&x_dest, &y_dest);
| Arguments | Description |
|---|---|
| x_dest | Specifies the addresses of the storage locations for the calculated Orbit X-coordinate. |
| y_dest | Specifies the addresses of the storage locations for the calculated Orbit Y-coordinate. |
Returns: None
Example
var targetX, targetY;
gfx_OrbitInit(&targetX, &targetY)
// This example sets the variables that will receive the result from a gfx_Orbit(..) function call
gfx_Orbit
Sets Prior to using this function, the destination address of variables for the calculated coordinates must be set using the gfx_OrbitInit(..) function. The gfx_Orbit(..) function calculates the x, y coordinates of a distant point relative to the current origin, where the only known parameters are the angle and the distance from the current origin. The new coordinates are calculated and then placed in the destination variables that have been previously set with the gfx_OrbitInit(..) function.
Syntax: gfx_Orbit(angle, distance);
| Arguments | Description |
|---|---|
| angle | Specifies the angle from the origin to the remote point. The angle is specified in degrees. |
| distance | Specifies the distance from the origin to the remote point in pixel units. |
Returns: None
Example
var targetX, targetY;
gfx_OrbitInit(&targetX, &targetY);
gfx_MoveTo(30, 30);
gfx_Bullet(5) // mark the start point with a small WHITE circle
gfx_Orbit(30, 50); // calculate a point 50 pixels away from origin at
// 30 degrees
gfx_CircleFilled(targetX,targetY,3,0xF800); // mark the target point
// with a RED circle
See example comments for explanation.
Note
Result is stored in the variables that were specified with the gfx_OrbitInit(..) function.
gfx_PutPixel
Draws a pixel at position x,y using the specified colour.
Syntax: gfx_PutPixel(x, y, colour);
| Arguments | Description |
|---|---|
| x,y | Specifies the screen coordinates of the pixel. |
| colour | Specifies the colour of the pixel. |
Returns: None
Example
gfx_GetPixel
Reads the colour value of the pixel at position x,y.
Syntax: gfx_GetPixel(x, y);
| Arguments | Description |
|---|---|
| x,y | Specifies the screen coordinates of the pixel colour to be returned. |
Returns: The 8 or 16bit colour of the pixel (default 16bit).
Example
gfx_PutPixel(20, 20, 1234);
r := gfx_GetPixel(20, 20);
print(r);
// This example print 1234, the colour of the pixel that was previously placed.
gfx_MoveTo
Moves the origin to a new position.
Syntax: gfx_MoveTo(xpos, ypos);
| Arguments | Description |
|---|---|
| xpos | Specifies the horizontal position of the new origin. |
| ypos | Specifies the vertical position of the new origin. |
Returns: None
Example
#inherit "4DGL_16bitColours.fnc"
func help()
var x, y, state;
print("TOUCHE ME");
touch_Set(TOUCH_ENABLE); // lets enable the touch screen
while(touch_Get(TOUCH_STATUS) != TOUCH_PRESSED); //Wait for touch
// we'll need a place on the screen to start with
gfx_MoveTo(touch_Get( TOUCH_GETX), touch_Get( TOUCH_GETY));
gfx_Set(OBJECT_COLOUR, WHITE); // this will be our line colour
while(1)
state := touch_Get(TOUCH_STATUS); // Look for touch activity
x := tou ch_Get(TOUCH_GETX); // Grab x and the
y := touch_Get(TOUCH_GETY); // y coordinates of the touch
if(state == TOUCH_PRESSED) // if there's a press
gfx_LineTo(x, y); // Draw a line from previous spot
endif
if(state == TOUCH_RELEASED) // if there's a release;
gfx_CircleFilled(x, y, 10, RED); // Draw a solid red circle
endif
if(state == TOUCH_MOVING) // if there's movement
gfx_PutPixel(x, y, LIGHT GREEN); // we'll draw a green pixel
endif
wend // Repeat forever
endfunc
gfx_MoveRel
Moves the origin to a new position relative to the old position.
Syntax: gfx_MoveRel(xoffset, yoffset);
| Arguments | Description |
|---|---|
| xoffset | Specifies the horizontal offset of the new origin. |
| yiffset | Specifies the vertical offset of the new origin. |
Returns: None
Example
gfx_MoveTo(10, 20);
gfx_MoveRel(-5, -3);
gfx_Dot();
// This example draws a pixel using the current object colour at x=5, y=17
gfx_IncX
Increment the current X origin by 1 pixel unit. The original value is returned before incrementing. The return value can be useful if a function requires the current point before insetting occurs.
Syntax: gfx_IncX();
Returns: The current X origin before the increment.
Example
var n;
gfx_MoveTo(20,20);
n := 96;
while (n--)
gfx_ObjectColour(n/3);
gfx_Bullet(2);
gfx_IncX();
wend
// This example draws a simple rounded vertical gradient.
gfx_IncY
Increment the current Y origin by 1 pixel unit. The original value is returned before incrementing. The return value can be useful if a function requires the current point before insetting occurs.
Syntax: gfx_IncY();
Returns: The current Y origin before the increment.
Example
var n;
gfx_MoveTo(20,20);
n := 96;
while (n--)
gfx_ObjectColour(n/3);
gfx_LineRel(20, 0);
gfx_IncY();
wend
// This example draws a simple horizontal gradient using lines.
gfx_LineTo
Draws a line from the current origin to a new position. The Origin is then set to the new position. The line is drawn using the current object colour. The line may be tessellated with the gfx_LinePattern(...) function.
Syntax: gfx_LineTo(xpos, ypos);
| Arguments | Description |
|---|---|
| xpos | Specifies the horizontal position of the line end as well as the new origin. |
| ypos | Specifies the vertical position of the line end as well as the new origin. |
Returns: None
Example
gfx_MoveTo(10, 20);
gfx_LineTo(60, 70);
// This example draws a line using the current object colour between x1=10,y1=20 and x2=60,y2=70. The new origin is now set at x=60,y=70.
gfx_LineRel
Draws a line from the current origin to a new position. The line is drawn using the current object colour. The current origin is not altered. The line may be tessellated with the gfx_LinePattern(...) function.
Syntax: gfx_LineRel(xpos, ypos);
| Arguments | Description |
|---|---|
| xpos | Specifies the horizontal end point of the line. |
| ypos | Specifies the vertical end point of the line. |
Returns: None
Example
gfx_LinePattern(0b1100110011001100);
gfx_MoveTo(10, 20);
gfx_LineRel(50, 50);
// This example draws a tessellated line using the current object colour between 10,20 and 50,50.
Note
The gfx_LinePattern(0); must be used after this to return line drawing to normal solid lines.
gfx_BoxTo
Draws a rectangle from the current origin to the new point using the current object colour. The top left corner is anchored by the current origin (x1, y1), the bottom right corner is specified by x2, y2.
Syntax: gfx_BoxTo(x2, y2);
| Arguments | Description |
|---|---|
| x2, y2 | Specifies the diagonally opposed corner of the rectangle to be drawn, the top left corner (assumed to be x1, y1) is anchored by the current origin. |
Returns: None
Example
gfx_MoveTo(40,40);
n := 10;
while (n--)
gfx_BoxTo(50,50);
gfx_BoxTo(30,30);
wend
// This example draws 2 boxes, anchored from the current origin.
Note
The default PEN_SIZE is set to OUTLINE, however, if PEN_SIZE is set to SOLID, the rectangle will be drawn filled, if PEN_SIZE is set to OUTLINE, the rectangle will be drawn as an outline. If the circle is drawn as SOLID, the outline colour can be specified with gfx_OutlineColour(...). If OUTLINE_COLOUR is set to 0, no outline is drawn.
gfx_SetClipRegion
Forces the clip region to the extent of the last text that was printed, or the last image that was shown.
Syntax: gfx_SetClipRegion();
Returns: None
Example
gfx_Ellipse
Plots a coloured Ellipse on the screen at centre x,y with xradius = xrad and yradius = yrad.
If PenSize = 0 Ellipse is Solid
If PenSize = 1 Ellipse is Outline
Syntax: gfx_Ellipse(x, y, xrad, yrad, colour);
| Arguments | Description |
|---|---|
| x, y | specifies the horizontal and vertical position of the centre of ellipse. |
| xrad, yrad | Specifies x-radius and y-radius of the ellipse. |
| colour | Specifies the colour for the lines. |
Returns: None
Example
gfx_EllipseFilled
Plots a solid coloured Ellipse on the screen at centre x,y with xradius = xrad and yradius = yrad.
Syntax: gfx_EllipseFilled(x, y, xrad, yrad, colour);
| Arguments | Description |
|---|---|
| x, y | specifies the horizontal and vertical position of the centre of ellipse. |
| xrad, yrad | Specifies x-radius and y-radius of the ellipse. |
| colour | Specifies the colour for the lines. |
Returns: None
Example
gfx_Button
Draws a 3-dimensional Text Button at screen location defined by x, y parameters (top left corner). The size of the button depends on the font, width, height and length of the text. The button can contain multiple lines of text by having the \n character embedded in the string for the end of line marker. In this case, the widest text in the string sets the overall width, and the height of the button is set by the number of text lines. In the case of multiple lines, each line is left justified. If you wish to centre or right justify the text, you will need to prepare the text string according to your requirements.
Syntax: gfx_Button(state, x, y, buttonColour, txtColour, font, txtWidth, txtHeight, text);
| Arguments | Description |
|---|---|
| state | 0 = Button pressed; 1 = Button raised. |
| x, y | Specifies the top left corner position of the button on the screen. |
| buttonColour | Button colour. |
| txtColour | Text Colour. |
| font | Specifies the Font ID. |
| txtWidth | Specifies the width of the text. This value is the font width multiplier and minimum value must be 1. |
| txtHeight | Specifies the height of the text. This value is the font height multiplier and minimum value must be 1. |
| text | Specifies the text string. The text string must be within the range of printable ascii character set. The string may have \n characters embedded to create a multiline button. |
Returns: None
Example
#constant LEFT 30
#constant TOP 150
#constant TEXTWIDTH 2
#constant TEXTHEIGHT 2
//------------------------------------------------------------
func main()
// Draw a button as a Text Box (indented)
gfx_Button(DOWN, 0, 30, GREEN, WHITE, FONT_4, TEXTWIDTH, TEXTHEIGHT, "4DGL Demo");
touch_Set(TOUCH_ENABLE);
repeat
// Draw the Push Button (raised)
gfx_Button(UP, LEFT, TOP, BLUE, RED, FONT 4, TEXTWIDTH, TEXTHEIGHT, " PRESS ");
// set touch detect region to that of the push button
touch_DetectRegion(LEFT, TOP, gfx_Get(RIGHT_POS), gfx_Get( BOTTOM_POS));
// Wait until the button is pressed
while(touch_Get(TOUCH_STATUS) != TOUCH_PRESSED);
// now redraw the Push Button (depressed)
gfx_Button(DOWN, LEFT, TOP, BLUE, WHITE, FONT_4, TEXTWIDTH, TEXTHEIGHT, " PRESS ");
// Wait until the button is pressed
while(touch_Get(TOUCH_STATUS) != TOUCH_RELEASED );
forever
endfunc
gfx_Panel
Draws a 3-dimensional rectangular panel at a screen location defined by x, y parameters (top left corner). The size of the panel is set with the width and height parameters. The colour is defined by colour The state parameter determines the appearance of the panel, 0 = recessed, 1 = raised.
Syntax: gfx_Panel(state, x, y, width, height, Colour);
| Arguments | Description |
|---|---|
| state | 0 = recessed; 1 = raised. |
| x, y | Specifies the top left corner position of the panel on the screen. |
| width | Specifies the width of the panel. |
| height | Specifies the Height of the panel. |
| colour | Specifies the colour of the panel. |
Returns: None
Example
#constant LEFT 15
#constant TOP 15
#constant WIDTH 100
#constant HEIGHT 100
func main()
// Draw a panel
gfx_Panel(RAISED, LEFT, TOP, WIDTH, HEIGHT, GRAY);
repeat forever
endfunc
gfx_Slider
Draws a vertical or horizontal slider bar on the screen. The gfx_Slider function has several different modes of operation. In order to minimise the amount of graphics functions we need, all modes of operation are selected naturally depending on the parameter values.
Selection rules:
- If x2-x1 > y2-y1 slider is assumed to be horizontal (i.e. if width > height, slider is horizontal).
- If x2-x1 <= y2-y1 slider is assumed to be vertical (i.e. if height <= width, slider is horizontal).
- If value is positive, thumb is set to the position that is the proportion of value to the scale parameter.(used to set the control to the actual value of a variable)
- If value is negative, thumb is driven to the graphics position set by the ABSolute of value. (used to set thumb to its actual graphical position (usually by touch screen)
- The thumb colour is determine by gfx_Set(OBJECT_COLOUR, value);, however, if the current object colour is BLACK, a darkened shade of the colour parameter is used for the thumb.
Syntax: gfx_Slider2(mode, x1, y1, x2, y2, colour, scale, value);
| Arguments | Description |
|---|---|
| mode | mode = 0 : Slider Indented, mode = 1 : Slider Raised, mode 2, Slider Hidden (background colour). |
| x1, y1 | Specifies the top left corner position of the slider on the screen. |
| x2, y2 | Specifies the bottom right corner position of the slider on the screen. |
| colour | Specifies the colour of the Slider bar. |
| scale | Scale = n : sets the full scale range of the slider for the thumb from 0 to n. |
| value | If value positive, sets the relative position of the thumb on the slider bar, else set thumb to ABS position of the negative number. |
Returns: If the value parameter was a positive number (i.e. value is a proportion of the scale parameter), the true (implied x-axis or y-axis) position of the thumb is returned.
If the value parameter was a negative number (i.e. thumb is being set to an ABSolute graphics position), the actual slider value (which is a proportion of the scale parameter) is returned.
Example
func drawRedSlider()
gfx_Slider(0,rSlider[0],rSlider[1],rSlider[2],rSlider[3],RED,255, valR);
txt_MoveCursor(1,12);
txt_Set(TEXT_OPACITY, OPAQUE);
txt_Set(TEXT_COLOUR, RED);
print (" ");
txt_MoveCursor(1,12);
print ([DEC] valR);
endfunc
gfx_ScreenCopyPaste
Copies an area of a screen from xs, ys of size given by width and height parameters and pastes it to another location determined by xd, yd.
Syntax: gfx_ScreenCopyPaste(xs, ys, xd, yd, width, height);
| Arguments | Description |
|---|---|
| xs, ys | Specifies the horizontal and vertical position of the top left corner of the area to be copied (source). |
| xd, yd | Specifies the horizontal and vertical position of the top left corner of where the paste is to be made (destination). |
| width | Specifies the width of the copied area. |
| height | Specifies the height of the copied area. |
Returns: None
Example
gfx_ScreenCopyPaste(10, 10, 100, 100, 40, 40);
// Copies 40x40 pixels originating from point (10,10) to (100,100);
gfx_RGBto565
Returns the 16bit (RED: 5, GREEN: 6, BLUE: 5 format) colour value of a 24bit (RED: 8, GREEN: 8, BLUE: 8 format) colour.
Syntax: gfx_RGBto565(RED, GREEN, BLUE);
| Arguments | Description |
|---|---|
| RED | 8bit colour value for RED. |
| GREEN | 8bit colour value for GREEN. |
| BLUE | 8bit colour value for BLUE. |
Returns: The 16bit (RED: 5, GREEN: 6, BLUE: 5 format) colour value.
Example
var colorRGB;
colorRGB := gfx_RGBto565(170, 126, 0); // convert 8bit Red, Green and Blue color values to 16bit 565 color value
gfx_332to565
Returns the 16bit (RED: 5, GREEN: 6, BLUE: 5 format) value of an 8bit (RED: 3, GREEN: 3, BLUE: 2 format) colour.
Syntax: gfx_332to565(COLOUR);
| Arguments | Description |
|---|---|
| COLOUR | 8bit colour value. 3bits for RED, 3bits for GREEN, 2bits for BLUE. |
Returns: The 16bit (RED: 5, GREEN: 6, BLUE: 5 format) value.
Example
var color565;
color565 := gfx_332to565(0b11010100); // Convert 8bit 332 color value to 16bit 565 color value
gfx_TriangleFilled
Draws a Solid triangle between vertices x1,y1, x2,y2 and x3,y3 using the specified colour.
Syntax: gfx_TriangleFilled(x1, y1, x2, y2, x3, y3, colour);
| Arguments | Description |
|---|---|
| x1, y1 | Specifies the first vertices of the triangle. |
| x2, y2 | Specifies the second vertices of the triangle. |
| x3, y3 | Specifies the third vertices of the triangle. |
| colour | Specifies the colour for the triangle. |
Returns: None
Example
gfx_TriangleFilled(10,10,30,10,20,30,CYAN);
// This example draws a CYAN Solid triangle with vertices at 10,10 30,10 20,30
gfx_PolygonFilled
Draws a solid Polygon between specified vertices: x1,y1, x2,y2 ... xn,yn using the specified colour. The last point is drawn back to the first point, completing the polygon. Vertices must be minimum of 3 and can be specified in any fashion.
Syntax: gfx_PolygonFilled(n, vx, vy, colour);
| Arguments | Description |
|---|---|
| n | Specifies the number of elements in the x and y arrays specifying the vertices for the polygon. |
| vx | Specifies the addresses of the storage of the array of elements for the x coordinates of the vertices. |
| vy | Specifies the addresses of the storage of the array of elements for the y coordinates of the vertices. |
| colour | Specifies the colour for the polygon. |
Returns: None
Example
var vx[7], vy[7];
func main()
vx[0] := 10; vy[0] := 10;
vx[1] := 35; vy[1] := 5;
vx[2] := 80; vy[2] := 10;
vx[3] := 60; vy[3] := 25;
vx[4] := 80; vy[4] := 40;
vx[5] := 35; vy[5] := 50;
vx[6] := 10; vy[6] := 40;
gfx_PolygonFilled(7, vx, vy, RED);
repeat forever
endfunc
// This example draws a simple filled polygon.
gfx_Origin
Sets relative screen offset for horizontal and vertical for the top left corner for graphics objects.
Syntax: gfx_Origin(x, y);
| Arguments | Description |
|---|---|
| x, y | Specifies the horizontal and vertical position of the top left corner of the clipping window. |
Returns: None
Example
gfx_Get
Returns various graphics parameters to caller.
The following graphics parameters can be queried:
| Mode | Description |
|---|---|
X_MAX |
Current orientations Max X Value (X_MAX) |
Y_MAX |
Current orientations Max Y Value (Y_MAX) |
LEFT_POS |
Left location of Object |
TOP_POS |
Top location of Object |
RIGHT_POS |
Right location of Object |
BOTTOM_POS |
Bottom location of Object |
X_ORG |
Get current internal X position |
Y_ORG |
Get current internal Y position |
Syntax: gfx_Get(mode);
| Arguments | Description |
|---|---|
| mode | Specifies graphics parameter to query. See the graphics parameters table above. |
Returns:
| Mode | Description |
|---|---|
| 0 | Returns the maximum horizontal value of the display. |
| 1 | Returns the maximum vertical value of the display. |
| 2 | Returns the left location of the last drawn object such as a slider or button or an image/video. |
| 3 | Returns the top location of the last drawn object such as a slider or button or an image/video. |
| 4 | Returns the right location of the last drawn object such as a slider or button or an image/video. |
| 5 | Returns the bottom location of the last drawn object such as a slider or button or an image/video. |
| 6 | Returns the internal X position that was set with gfx_MoveTo(x, y); or gfx_Set(X_ORG, pos); |
| 7 | Returns the internal Y position that was set with gfx_MoveTo(x, y); or gfx_Set(X_ORG, pos); |
Example
var := gfx_Get(X_MAX); //Returns the maximum horizontal resolution of the display
var := gfx_Get(0);
var := gfx_Get(Y_MAX); //Returns the maximum vertical resolution of the display
var := gfx_Get(1);
var := gfx_Get(RIGHT_POS); //Returns the right location of the last drawn object
//that only has top, left parameters such as a button
// or an image/video.
var := gfx_Get(2);
var := gfx_Get(BOTTOM_POS); //Returns the bottom location of the last drawn object
//that only has top, left parameters such as a button
//or an image/video.
var := gfx_Get(3);
gfx_ClipWindow
Specifies a clipping window region on the screen such that any objects and text placed onto the screen will be clipped and displayed only within that region. For the clipping window to take effect, "Clipping" setting must be enabled separately using gfx_Set(CLIPPING, ON) or the shortcut gfx_Clipping(ON).
Syntax: gfx_ClipWindow(x1, y1, x2, y2);
| Arguments | Description |
|---|---|
| x1, y1 | Specifies the horizontal and vertical position of the top left corner of the clipping window. |
| x2, y2 | Specifies the horizontal and vertical position of the bottom right corner of the clipping window. |
Returns: None
Example
var n;
gfx_ClipWindow(10, 10, 50, 50 )
n := 50000;
while(n--)
gfx_PutPixel(RAND()%100, RAND()%100, RAND());
wend
repeat forever
// This example will draw 50000 random colour pixels, only the pixels within the clipping area will be visible
gfx_Set
Given a function number and a value, set the required graphics control parameter, such as size, colour, and other parameters. (See the Single parameter short-cuts for the gfx_Set functions below). It is strongly recommended to use the pre-defined constants rather than the mode numbers.
Single parameter short-cuts for the gfx_Set functions
| Predefined Name | Description | Value |
|---|---|---|
| PEN_SIZE | Set the draw mode for gfx_LineTo, gfx_LineRel, gfx_Dot, gfx_Bullet and gfx_BoxTo (default mode is OUTLINE)* | 0 or SOLID 1 or OUTLINE |
| BACKGROUND_COLOUR | Set the screen background colour | Colour, 0-65535 |
| OBJECT_COLOUR | Generic colour for gfx_LineTo, gfx_LineRel, gfx_Dot, gfx_Bullet and gfx_BoxTo | Colour, 0-65535 |
| CLIPPING | Turns clipping on/off. The clipping points are set with gfx_ClipWindow and must be set first. |
1 or 0 (ON or OFF) |
| TRANSPARENT_COLOUR | Colour that needs to be made transparent. | Colour, 0-65535 |
| TRANSPARENCY | Turn the transparency ON or OFF. Transparency is automatically turned OFF after the next image or video command. | 1 or 0 (ON or OFF) |
| FRAME_DELAY | Set the inter frame delay for media_Video | 0 to 255msec |
| SCREEN_MODE | Set required screen behaviour/orientation. | 0 or LANDSCAPE 1 or LANDSCAPE_R 2 or PORTRAIT 3 or PORTRAIT_R |
| OUTLINE_COLOUR | Outline colour for rectangles and circles(set to 0 for no effect) | Colour, 0-65535 |
| CONTRAST | OLED MODULES: Set contrast value, 0 = display off, 1-9 = contrast level LCD MODULES: contrast 0 = display OFF, non-zero = display ON EXCEPTION: uLCD-43 supports Contrast values from 1-15 and 0 to turn the Display off. 3202X-P1 supports Contrast values from 1 to 9 and 0 to turn the Display off. |
0 or OFF 1 to 9 for levels 1 or 0 (ON or OFF) |
| BEVEL_WIDTH | Set Button Bevel Width, 0 pixel to 15pixels. | 0 None 1 to 15 pixels |
| SCREEN_RES | Set VGA Screen resolution. Applies to uVGA-II/III only | 0 for 320x240 1 for 640 x 480 2 for800 x 480 |
| DISPLAY_PAGE | Choose Page to be displayed. Value depends on the resolution set. Applies to uVGA-II/III and uLCD-43 only. | e.g. 00hex-04hex for 320x240 resolution on a uVGA-II/III. |
| READ_PAGE | Choose Page to be read. Value depends on the resolution set. Applies to uVGA-II/III and uLCD-43 only. | e.g. 00hex-04hex for 320x240 resolution on a uVGA-II/III. |
| WRITE_PAGE | Choose Page to be written. Value depends on the resolution set. Applies to uVGA-II/III and uLCD-43 only. | e.g. 00hex-04hex for 320x240 resolution on a uVGA-II/III. |
Single parameter short-cuts for the gfx_Set functions
| Function Syntax | Function Action | Value |
|---|---|---|
gfx_PenSize(mode) |
Set the draw mode for gfx_LineTo, gfx_LineRel, gfx_Dot, gfx_Bullet and gfx_BoxTo* | 0 or SOLID 1 or OUTLINE |
gfx_BGcolour(colour) |
Set the screen background colour | Colour 0-65535 |
gfx_ObjectColour(colour) |
Generic colour for gfx_LineTo, gfx_LineRel, gfx_Dot, gfx_Bullet and gfx_BoxTo | Colour 0-65535 |
gfx_Clipping(mode) |
Turns clipping on/off. The clipping points are set with gfx_ClipWindow. |
0 or 1 (ON or OFF) |
gfx_TransparentColour(colour) |
Colour that needs to be made transparent. | Colour, 0-65535 |
gfx_Transparency(mode) |
Turn the transparency ON or OFF. | 0 or 1 (ON or OFF) |
gfx_FrameDelay(delay) |
Set the inter frame delay for media_Video. | 0 to 255msec |
gfx_ScreenMode(mode) |
Graphics orientation LANDSCAPE, LANDSCAPE_R, PORTRAIT, PORTRAIT_R | 1 or LANDSCAPE 2 or LANDSCAPE_R 3 or PORTRAIT 4 or PORTRAIT_R |
gfx_OutlineColour(colour) |
Outline colour for rectangles and circles.(set to 0 for no effect) | Colour 0-65535 |
gfx_Contrast(value) |
OLED MODULES: Set contrast value, 0 = display off, 1-9 = contrast level LCD MODULES: contrast 0 = display OFF, non-zero = display ON EXCEPTION: uLCD-43 supports Contrast values from 1-15 and 0 to turn the Display off. 3202X-P1 supports Contrast values from 1 to 9 and 0 to turn the Display off. |
0 or OFF 1 to 9 for levels 1 or 0 (ON or OFF) |
gfx_LinePattern(pattern) |
Sets the line draw pattern for line drawing. If set to zero, lines are solid, else each '1' bit represents a pixel that is turned off. See code examples for further reference. | 0 bits for pixels on 1 bits for pixels off |
gfx_ColourMode(mode) |
Sets 8 or 16bit colour mode. Function not available, fixed as 16bit mode. |
0 or COLOUR16 1 or COLOUR8 |
gfx_BevelWidth(mode) |
graphics button bevel width | 0 None 1 to 15 pixels |
gfx_BevelShadow(value) |
graphics button bevel shadow depth | |
gfx_Xorigin(offset) |
graphics X origin | |
gfx_Yorigin(offset) |
graphics Y origin |
Syntax: gfx_Set(function, value);
| Arguments | Description |
|---|---|
| function | The function number determines the required action for various graphics control functions. Usually a constant, but can be a variable, array element, or expression. There are pre-defined constants for each of the functions. |
| mode | A variable, array element, expression or constant holding a value for the selected function. |
Returns: None
Example
Note
Does not apply to uVGA-II/III modules.
I2C Master Functions
I2C_Open
Calling this function configures the I2C module and initialises it to be ready for service. The I2C clock speed is specified by the speed parameter. Three I2C Speed settings are available to suit various requirements.
| Constant | Speed |
|---|---|
| I2C_SLOW | 100KHz |
| I2C_MED | 400KHz |
| I2C_FAST | 1MHz |
Syntax: I2C_Open(Speed);
| Arguments | Description |
|---|---|
| Speed | Specifies the I2C bus speed. (See the table above). |
Returns: None
Example
I2C_Close
Calling this function closes the I2C port and disables the I2C hardware
Syntax: I2C1_Close();
Returns: None
Example
I2C_Start
Calling this function sends an I2C start condition. The hardware first pulls the SDA (data) line low, and next pulls the SCL (clock) line low.
Syntax: I2C_Start();
Returns: None.
Example
I2C_Stop
Calling this function sends an I2C stop condition. The hardware first releases the SCL to high state, and then releases the SDA line high.
Syntax: I2C_Stop();
Returns: None.
Example
I2C_Restart
Calling this function generates a restart condition.
Syntax: I2C_Restart();
Returns: None.
Example
I2C_Read
Calling this function reads a single byte from the I2C bus.
Syntax: I2C_Read();
Returns: Byte from the I2C Bus in the lower 8-bits.
Example
Note
Data can only change when the clock is low.
I2C_Write
Calling this function sends a single byte to the I2C bus
Syntax: I2C_Write(byte);
| Arguments | Description |
|---|---|
| byte | The byte to be written to the I2C Bus. |
Returns:
- 0 if False/Fail
- 1 if Success/OK
- 2 if NAK from device (or device does not exist)
Example
I2C_Ack
Calling this function sends an I2C acknowledge condition. The hardware first pulls the SDA line low, and next releases SCL high followed by pulling SCL low again thus generating a clock pulse, SDA is then released high.
Syntax: I2C_Ack();
Returns: None
Example
Note
Data can only change when the clock is low.
I2C_Nack
Calling this function sends an I2C negative acknowledge condition. The hardware first release the SDA line high, and next releases SCL HI followed by pulling SCL low thus generating a clock pulse.
Syntax: I2C_Nack();
Returns: None
Example
Note
Data can only change when the clock is low.
I2C_AckStatus
Call this function to get the ACK status from the slave device The state of SDA is returned.
Syntax: I2C_AckStatus();
Returns: Device Ack Status.
Example
Note
Returns the state of SDA after the last clock pulse.
I2C_AckPoll
Call this function to wait for a device to return an ACK during ACK polling. The SDA is monitored for an Ack.
Syntax: I2C_AckPoll(control);
| Arguments | Description |
|---|---|
| control | The control word to be written to the device. |
Returns: Device Ack Status.
Example
r := I2C_AckPoll(0xA0); //send the control byte the wait for a device
//to return poll the device until an ACK
//is received.
Note
Returns the state of SDA after the last clock pulse.
I2C_Idle
Call this function to wait until the I2C bus is inactive.
Syntax: I2C_Idle();
Returns: Device Ack Status.
Example
Note
Wait for the bus to become idle.
I2C_Gets
Reads up to size characters into buffer from an ascii string stored in a device. Reads up to the ASCII NULL terminator and includes the terminator.
Syntax: I2C_Gets(buffer, size);
| Arguments | Description |
|---|---|
| buffer | Storage for the string being read from the device. |
| size | Maximum size of the string to be read. |
Returns: The count of bytes actually read.
Example
I2C_Getn
Reads count bytes in to buffer and returns True if function succeeds.
Syntax: I2C_Getn(buffer, count);
| Arguments | Description |
|---|---|
| buffer | Storage for the bytes being read from the device. |
| size | Number of bytes to be read. |
Returns: True if block read ok, otherwise False.
Example
I2C_Puts
Writes an ASCII string from buffer to a device. The ASCII NULL terminator is also written.
Syntax: I2C_Puts(buffer);
| Arguments | Description |
|---|---|
| buffer | Storage for the string being written to the device. |
Returns: The count of the bytes actually written.
Example
I2C_Putn
Writes count bytes from the buffer to the device, and returns count if function succeeds.
Syntax: I2C_Putn(buffer, count);
| Arguments | Description |
|---|---|
| buffer | Storage for the bytes being written to the device. |
| count | Number of bytes to be written. |
Returns: Number of bytes written.
Example
Image Control Functions
img_SetPosition
This function requires that an image control has been created with the file_LoadImageControl(...); function.
Sets the position where the image will next be displayed. Returns TRUE if index was ok and function was successful. (the return value is usually ignored).
You may turn off an image so when img_Show() is called, the image will not be shown.
This function requires that an image control has been created with the file_LoadImageControl(...); function.
Syntax: img_SetPosition(handle, index, xpos, ypos);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
| xpos | Top left horizontal screen position where image is to be displayed. |
| ypos | Top left vertical screen position where image is to be displayed. |
Returns: True if index OK, otherwise false.
Example
// make a simple 'window'
gfx_Panel(PANEL_RAISED, 0, 0, 239, 239, GRAY);
img_SetPosition(Ihndl, BTN_EXIT, 224,2); //set checkout box position
img_Enable(Ihndl, BTN_EXIT); //enable checkout box
img_Enable
This function requires that an image control has been created with the file_LoadImageControl(...); function.
Enables a selected image in the image list. Returns TRUE if index was ok and function was successful. This is the default state so when img_Show() is called all the images in the list will be shown.
To enable all the images in the list at the same time set index to -1.
To enable a selected image, use the image index number.
Syntax: img_Enable(handle, index);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
Returns: True if index OK, otherwise False.
Example
img_Disable
This function requires that an image control has been created with the file_LoadImageControl(...); function.
Disables an image in the image list. Returns TRUE if index was ok and function was successful. Use this function to turn off an image so that when img_Show() is called the selected image in the list will not be shown.
To disable all the images in the list at the same time set index to -1.
Syntax: img_Disable(handle, index);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
Returns: True if index OK, otherwise False.
Example
img_Darken
This function requires that an image control has been created with the file_LoadImageControl(...); function.
Darken an image in the image list. Returns TRUE if index was ok and function was successful. Use this function to darken an image so that when img_Show() is called the control will take effect. To darken all the images in the list at the same time set index to -1.
Syntax: img_Darken(handle, index);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
Returns: True if index OK, otherwise False.
Example
Note
This feature will take effect one time only and when img_Show() is called again the darkened image will revert back to normal.
img_Lighten
This function requires that an image control has been created with the file_LoadImageControl(...); function.
Lighten an image in the image list. Returns TRUE if index was ok and function was successful. Use this function to lighten an image so that when img_Show() is called the control will take effect. To lighten all the images in the list at the same time set index to -1.
Syntax: img_Lighten(handle, index);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
Returns: True if index OK, otherwise False.
Example
Note
This feature will take effect one time only and when img_Show() is called again the lightened image will revert back to normal.
img_SetWord
This function requires that an image control has been created with the file_LoadImageControl(...); function. Set specified word in an image entry.
| Offset Constant | Value | Description |
|---|---|---|
| IMAGE_XPOS | 2 | WORD image location X |
| IMAGE_YPOS | 3 | WORD image location Y |
| IMAGE_FLAGS | 6 | WORD image flags |
| IMAGE_DELAY | 7 | WORD inter frame delay |
| IMAGE_INDEX | 9 | WORD current frame |
| IMAGE_TAG | 12 | WORD user variable #1 |
| IMAGE_TAG2 | 13 | WORD user variable #2 |
Syntax: img_SetWord(handle, index, offset, word);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
| offset | Offset of the required word in the image entry. |
| word | The word to be written to the entry. |
Returns: TRUE if successful, return value usually ignored.
Example
func cat()
var private frame := 0; // start with frame 0
var private image := SPRITE_CAT; // cat image, can be changed with
// cat.image := xxx
var private speed := 30;
img_SetWord(Ihndl, image, IMAGE_INDEX, frame++);
frame := frame % img_GetWord(Ihndl, image, IM AGE_FRAMES);
img_Show(Ihndl, image);
sys_SetTimer(TIMER3,speed); // reset the event timer
endfunc
Note
Not all Constants are listed as some are Read Only. img_Show(..) will now show error box for out of range video frames. Also, if frame is set to -1, just a rectangle will be drawn in background colour to blank an image. It applies to PmmC R29 or above.
img_GetWord
This function requires that an image control has been created with the file_LoadImageControl(...) function.
Returns specified word from an image entry.
| Offset Constant | Value | Description |
|---|---|---|
| IMAGE_LOWORD | 0 | WORD image address LO |
| IMAGE_HIWORD | 1 | WORD image address HI |
| IMAGE_XPOS | 2 | WORD image location X |
| IMAGE_YPOS | 3 | WORD image location Y |
| IMAGE_WIDTH | 4 | WORD image width |
| IMAGE_HEIGHT | 5 | WORD image height |
| IMAGE_FLAGS | 6 | WORD image flags |
| IMAGE_DELAY | 7 | WORD inter frame delay |
| IMAGE_FRAMES | 8 | WORD number of frames |
| IMAGE_INDEX | 9 | WORD current frame |
| IMAGE_CLUSTER | 10 | WORD image start cluster pos (for FAT16 only) |
| IMAGE_SECTOR | 11 | WORD image start sector in cluster pos (for FAT16 only) |
| IMAGE_TAG | 12 | WORD user variable #1 |
| IMAGE_TAG2 | 13 | WORD user variable #2 |
Syntax: img_GetWord(handle, index, offset);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
| offset | Offset of the required word in the image entry. |
Returns: The image entry in the list.
Example
img_Show
This function requires that an image control has been created with the file_LoadImageControl(...) function.
Enable the displaying of the image entry in the image control.
Syntax: img_Show(handle, index);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
Returns: True if successful, usually ignored.
Example
img_SetAttributes
This function SETS one or more bits in the IMAGE_FLAGS field of an image control entry. "value" refers to various bits in the image control entry (see image attribute flags).
A '1' bit in the "value" field SETS the respective bit in the IMAGE_FLAGS field of the image control entry.
| Flag Constant | Bit | Value | Description |
|---|---|---|---|
| I_ENABLED | 15 | 0x8000 | Set for image enabled. |
| I_DARKEN | 14 | 0x4000 | Display dimmed. |
| I_LIGHTEN | 13 | 0x2000 | Display bright. |
| I_TOUCHED | 12 | 0x1000 | Touch test result. |
| I_Y_LOCK | 11 | 0x0800 | Stop Y movement. |
| I_X_LOCK | 10 | 0x0400 | Stop X movement. |
| I_TOPMOST | 9 | 0x0200 | Draw on top of other images next update. |
| I_STAYONTOP | 8 | 0x0100 | Draw on top of other images always. |
| I_TOUCH_DISABLE | 5 | 0x0020 | Set to disable touch for this image, default=1 for movie, 0 for image. |
Syntax: img_SetAttributes(handle, index, value);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
| value | Refers to various bits in the image control entry (see image attribute flags). |
Returns: True if successful, usually ignored.
Example
:
:
img_Enable(Ihndl, SPRITE_CAT); // we'll also use small cat video
img_SetAttributes(Ihndl, SPRITE_CAT, I_NOGROUP);
img_SetPosition(Ihndl, SPRITE_CAT, 160, 180); // set its position
:
img_ClearAttributes
Clear various image attribute flags in an image control entry. (see image attribute flags below)
This function requires that an image control has been created with the file_LoadImageControl(...) function.
| Flag Constant | Bit | Value | Description |
|---|---|---|---|
| I_ENABLED | 15 | 0x8000 | Set for image enabled. |
| I_DARKEN | 14 | 0x4000 | Display dimmed. |
| I_LIGHTEN | 13 | 0x2000 | Display bright. |
| I_TOUCHED | 12 | 0x1000 | Touch test result. |
| I_Y_LOCK | 11 | 0x0800 | Stop Y movement. |
| I_X_LOCK | 10 | 0x0400 | Stop X movement. |
| I_TOPMOST | 9 | 0x0200 | Draw on top of other images next update. |
| I_STAYONTOP | 8 | 0x0100 | Draw on top of other images always. |
| I_TOUCH_DISABLE | 5 | 0x0020 | Set to disable touch for this image, default=1 for movie, 0 for image. |
Syntax: img_ClearAttributes(handle, index, value);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
| value | a '1' bit indicates that a bit should be set and a '0' bit indicates that a bit is not altered. |
Note
If index is set to -1, the attribute is altered in ALL of the entries in the image list. The constant ALL is set to -1 specifically for this purpose.
Returns: Returns TRUE if if index was ok and function was successful, usually ignored
Example
Note
Image attribute flags may be combined with the + or | operators, e.g.:- img_ClearAttributes(hndl, ALL, I_Y_LOCK | I_X_LOCK ); // allow all images to move in any direction.
img_Touched
This function requires that an image control has been created with the file_LoadImageControl(...) function.
Returns index if image touched or returns -1 image not touched. If index is passed as -1 the function tests all images and returns -1 if image not touched or returns index.
Syntax: img_Touched(handle, index);
| Arguments | Description |
|---|---|
| handle | Pointer to the Image List. |
| index | Index of the images in the list. |
Returns: index of image touched, released or being held, or -1 if none
Example
if(state == TOUCH_PRESSED)
n := img_Touched(Ihndl, -1); //scan image list, looking for a touch
if(n != -1)
last := n;
button := n;
img_Lighten(Ihndl, n); //lighten the button touched
img_Show(Ihndl, -1); // restore the images
endif
endif
Math Functions
ABS
This function returns the absolute value of value.
Syntax: ABS(value);
| Arguments | Description |
|---|---|
| value | A variable, array element, expression or constant. |
Returns: The absolute value.
Example
var myvar, number;
number :=100;
myvar := ABS(number * 5);
// This example returns 500 in variable myvar.
MIN
This function returns the smallest of value1 and value2.
Syntax: MIN(value1, value2);
| Arguments | Description |
|---|---|
| value1 | A variable, array element, expression or constant. |
| value2 | A variable, array element, expression or constant. |
Returns: The smallest of the two values.
Example
var myvar, number1, number2;
number1 := 33;
number2 := 66;
myvar := MIN(number1, number2);
// This example returns 33 in variable myvar.
MAX
This function returns the largest of value1 and value2.
Syntax: MAX(value1, value2);
| Arguments | Description |
|---|---|
| value1 | A variable, array element, expression or constant. |
| value2 | A variable, array element, expression or constant. |
Returns: The largest of the two values.
Example
var myvar, number1, number2;
number1 := 33;
number2 := 66;
myvar := MAX(number1, number2);
// This example returns 66 in variable myvar.
SWAP
Given the addresses of two variables (var1 and var2), the values at these addresses are swapped.
Syntax: SWAP(&var1, &var2);
| Arguments | Description |
|---|---|
| &var1 | The address of the first variable. |
| &var2 | The address of the second variable. |
Returns: None
Example
var number1, number2;
number1 := 33;
number2 := 66;
SWAP(number1, number2);
// This example swaps the values in number1 and number2. After the function is executed, number1 will hold 66, and number2 will hold 33.
SIN
This function returns the SIN of an angle.
Syntax: SIN(angle);
| Arguments | Description |
|---|---|
| angle | The angle in degrees. |
Note
The input value is automatically shifted to lie within 0-359 degrees.
Returns: The sine in radians of an argument specified in degrees. The returned value range is from 127 to -127 which is a more useful representation for graphics work. The real sine values vary from 1.0 to -1.0 so appropriate scaling must be done in user code as required.
Example
COS
This function returns the COSINE of an angle.
Syntax: COS(angle);
| Arguments | Description |
|---|---|
| angle | The angle in degrees. |
Note
The input value is automatically shifted to lie within 0-359 degrees.
Returns: The cosine in radians of an argument specified in degrees. The returned value range is from 127 to -127 which is a more useful representation for graphics work. The real sine values vary from 1.0 to -1.0 so appropriate scaling must be done in user code as required.
Example
RAND
This function returns a pseudo random signed number ranging from -32768 to +32767.
The random number generator may first be seeded by using the SEED(number) function. The seed will generate a pseudo random sequence that is repeatable. You can use the modulo operator (%) to return a number within a certain range, e.g. n := RAND() % 100; will return a random number between -99 and +99. If you are using random number generation for random graphics points, or only require a positive number set, you will need to use the ABS function so only a positive number is returned, e.g.: X1 := ABS(RAND() % 100); will set co-ordinate X1 between 0 and 99.
Syntax: RAND();
Returns: A pseudo random signed number ranging from -32768 to +32767 each time the function is called.
Example
Note
If the random number generator is not seeded, the first number returned after reset or power up will be zero. This is normal behavior.
SEED
This function seeds the pseudo random number generator so it will generate a new repeatable sequence. The seed value can be a positive or negative number.
Syntax: SEED(number);
| Arguments | Description |
|---|---|
| number | Specifies the seed value for the pseudo random number generator. |
Returns: None
Example
SQRT
This function returns the integer square root of a number.
Syntax: SQRT(number);
| Arguments | Description |
|---|---|
| number | Specifies the positive number for the SQRT function. |
Returns: The integer square root which is the greatest integer less than or equal to the square root of number.
Example
var myvar;
myvar := SQRT(26000);
// This example returns 161 in variable myvar which is the integer square root of 26000.
OVF
This function returns the high order 16-bits from certain math and shift functions. It is extremely useful for calculating 32-bit address offsets for MEDIA access.
It can be used with the shift operations, addition, subtraction, multiplication and modulus operations.
Syntax: OVF();
Returns: The high order 16-bits from certain math and shift functions.
Example
var loWord, hiWord;
loWord := 0x2710 * 0x2710; // (10000 * 10000 in hexformat)
hiWord := OVF();
print ("0x", [HEX] hiWord, [HEX]loWord);
// This example will print 0x05F5E100 to the display , which is 100,000,000 in hexadecimal
CY
This function returns the carry status of an unsigned overflow from any 16 or 32bit additions or subtractions.
Syntax: CY();
Returns: Status of carry, 0 or 1.
Example
var myvar;
myvar := 0xFFF8 + 9; // result = 1
print(“myvar ”, myvar,"\nCarry ", CY(),"\n"); // carry = 1
/*
This example will print
myvar 1
Carry 1
*/
uadd_3232
Performs an unsigned addition of 2 x 32bit values placing the 32bit result in a 2 word array.
Syntax: uadd_3232(&res32, &val1, &val2);
| Arguments | Description |
|---|---|
| &res32 | Points to 32bit result register. |
| &val1 | Points to 32bit augend. |
| &val2 | Points to 32bit addend. |
Returns: Returns 1 on 32bit unsigned overflow (carry). Carry flag is also set on 32bit unsigned overflow and can be read with the CY() function.
Example
var carry, valA[2], valB[2], Result[2];
var p;
valA[0] := 0;
valA[1] := 1;
valB[0] := 0;
valB[1] := 1;
carry := uadd_3232(Result, valA, valB);
p := str_Ptr(Result);
print("0x");
str_Printf(&p, "%lX"); //prints the value at pointer in Hex long format.
// This example will print 0x20000.
usub_3232
Performs an unsigned subtraction of 2 x 32bit values placing the 32bit result in a 2 word array.
Syntax: usub_3232(&res32, &val1, &val2);
| Arguments | Description |
|---|---|
| &res32 | Points to 32bit result register. |
| &val1 | Points to 32bit minuend. |
| &val2 | Points to 32bit subtrahend. |
Returns: Returns 1 on 32bit unsigned overflow (carry). Carry flag is also set on 32bit unsigned overflow and can be read with the CY() function.
Example
var carry, valA[2], valB[2], Result[2];
var p;
valA[0] := 0;
valA[1] :=0xFFFF;
valB[0] := 0;
valB[1] := 0xEFFF;
carry := usub_3232(Result, valA, valB);
p := str_Ptr(Result);
print("0x");
str_Printf(&p, "%lX");
repeat forever
// This example will print 0x10000000.
umul_1616
Performs an unsigned multiply of 2 x 16bit values placing the 32bit result in a 2 word array.
Syntax: umul_1616(&res32, val1, val2);
| Arguments | Description |
|---|---|
| &res32 | Points to 32bit result register. |
| val1 | 16bit register or constant. |
| val2 | 16bit register or constant. |
Returns: A pointer to the 32bit result. Carry and overflow are not affected.
Example
var val32[2];
var p;
umul_1616(val32, 500, 2000);
p := str_Ptr(val32);
str_Printf(&p, "%ld");
// This example prints 1000000.
ucmp_3232
Performs an unsigned comparison of 2 x 32bit values.
Syntax: ucmp_3232(&val1, &val2);
| Arguments | Description |
|---|---|
| &val1 | Points to 32bit variable. |
| &val2 | Points to 32bit variable. |
Returns: 0 if equal. 1 if val1 > val2. -1 if val1 < val2
Example
var carry, valA[2], valB[2], Result;
valA[0] := 0;
valA[1] := 0xFFFF;
valB[0] := 0;
valB[1] :=0xEFFF;
Result := cmp_3232(valA, valB); //val1 > val2
print(Result);
repeat forever
// This example will print 1.
Media Functions
media_Init
Initialise a uSD/SD/SDHC memory card for further operations. The SD card is connected to the SPI (serial peripheral interface) of the Picaso chip.
Syntax: media_Init();
Returns: 1 if memory card is present and successfully initialised. 0 if no card is present or not able to initialise.
Example
while(!media_Init())
gfx_Cls();
pause(300);
puts(“Please insert SD card”);
pause(300);
wend
// This example waits for SD card to be inserted and initialised, flashing a message if no SD card detected.
media_SetAdd
Set media memory internal Address pointer for access at a non sector aligned byte address.
Syntax: media_SetAdd(HIword, LOword);
| Arguments | Description |
|---|---|
| HIword | Specifies the high word (upper 2 bytes) of a 4 byte media memory byte address location. |
| LOword | Specifies the low word (lower 2 bytes) of a 4 byte media memory byte address location. |
Returns: None
Example
media_SetAdd(0, 513);
// This example sets the media address to byte 513 (which is sector #1, 2nd byte in sector) for subsequent operations.
media_SetSector
Set media memory internal Address pointer for sector access.
Syntax: media_SetSector(HIword, LOword);
| Arguments | Description |
|---|---|
| HIword | Specifies the high word (upper 2 bytes) of a 4 byte media memory sector address location. |
| LOword | Specifies the low word (lower 2 bytes) of a 4 byte media memory sector address location. |
Returns: Result
Example
media_SetSector(0, 10);
// This example sets the media address to the 11th sector (which is also byte address 5120) for subsequent operations.
media_RdSector
Reads and Returns 512 bytes (256 words) into a destination block (e.g. rdblock[256]) pointed to by the internal Sector pointer. After the read the Sector pointer is automatically incremented by 1.
Syntax: media_RdSector(Destination_Address);
| Arguments | Description |
|---|---|
| Destination_Address | Destination block pointed to by the internal Sector pointer. |
Returns: TRUE if media response was TRUE. 512 bytes (256 words) in to a destination block.
Example
var rdblock[256];
media_SetSector(0,10);
if (media_RdSector(rdblock));
print(“Data collected”);
endif
// This example sets a 512 bytes block and collects data from the address pointed to by media_SetSector command.
media_WrSector
Writes 512 bytes (256 words) from a source memory block (e.g. wrblock[256]) into the uSD card.
After the write, the Sect pointer is automatically incremented by 1.
Syntax: media_WrSector(Source_Address);
| Arguments | Description |
|---|---|
| Source_Address | Source memory block of 512bytes. |
Returns: TRUE if media response was TRUE.
Example
var wrblock[256];
func main()
prepare_block();
media_SetSector(0,10)
if (media_WrSector(wrblock));
print(“Data transferred”);
endif
:
:
// This example sets a 512 bytes block and transfers data to the address pointed to by media_SetSector command.
media_ReadByte
Returns the byte value from the current media address. The internal byte address will then be internally incremented by one.
Syntax: media_ReadByte();
Returns: Byte value.
Example
var LObyte, HIbyte;
if(media_Init())
media_SetAdd(0, 510);
LObyte := media_ReadByte();
HIbyte := media_ReadByte();
print([HEX2]HIbyte,[HEX2]LObyte);
endif
repeat forever
// This example initialises the media, sets the media byte address to 510, and reads the last 2 bytes from sector 0. If the card happens to be FAT formatted, the result will be “AA55”. The media internal address is internally incremented for each of the byte operations.
media_ReadWord
Returns the word value (2 bytes) from the current media address. The internal byte address will then be internally incremented by two. If the address is not aligned, the word will still be read correctly.
Syntax: media_ReadWord();
Returns: Returns the word value (2 bytes) from the current media address.
Example
var myword;
if(media_Init())
media_SetAdd(0, 510);
myword := media_ReadWord();
print([HEX4]myword);
endif
repeat forever
// This example initialises the media, sets the media byte address to 510 and reads the last word from sector 0. If the card happens to be formatted, the result will be “AA55”.
media_WriteByte
Writes a byte to the current media address that was initially set with media_SetSector(...);.
Syntax: media_WriteByte(byte_val);
| Arguments | Description |
|---|---|
| byte_val | The lower 8-bits specifies the byte to be written at the current media address location. |
Returns: Non-zero if write was successful.
Example
var n, char;
while (media_Init()==0); // wait if no SD card detected
media_SetSector(0, 2); // at sector 2
//media_SetAdd(0, 1024); // (alternatively, use media_SetAdd(),
// lower 9 bits
while (n < 10)
media_WriteByte(n++ +'0'); // write ASCII '0123456789' to the
wend // first 10 locations.
to(MDA); putstr("Hello World"); // now write a ascii test string
media_WriteByte('A'); // write a further 3 bytes
media_WriteByte('B');
media_WriteByte('C');
media_WriteByte(0); // terminate with zero
media_Flush(); // we're finished, close the sector
media_SetAdd(0, 1024+5); // set the starting byte address
while(char:=media_ReadByte()) putch(char); // print result, starting
// from '5'
repeat forever
// This example initialises the media, writes some bytes to the required sector, then prints the result from the required location.
Note
Writing bytes or words to a media sector must start from the beginning of the sector. All writes will be incremental until the media_Flush() function is executed, or the sector address rolls over to the next sector. When media_Flush() is called, any remaining bytes in the sector will be padded with 0xFF, destroying the previous contents. An attempt to use the media_SetAdd(..) function will result in the lower 9 bits being interpreted as zero. If the writing rolls over to the next sector, the media_Flush() function is issued automatically internally.
media_WriteWord
Writes a word to the current media address that was initially set with media_SetSector(...);.
Syntax: media_WriteWord(word_val);
| Arguments | Description |
|---|---|
| word_val | The 16-bit word to be written at the current media address location. |
Returns: Non-zero if write was successful.
Example
var n;
while (media_Init()==0); // wait until a good SD card is found
n:=0;
media_SetAdd(0, 1536); // set the starting byte address
while (n++ < 20)
media_WriteWord(RAND()); // write 20 random words to first 20
wend // word locations.
n:=0;
while (n++ < 20)
media_WriteWord(n++*1000);// write sequence of 1000*n to next 20
wend // word locations.
media_Flush(); // we're finished, close the sector
media_SetAdd(0, 1536+40); // set the starting byte address
n:=0;
while(n++<8) // print result of fist 8 multiplication calcs
print([HEX4] media_ReadWord()," n");
wend
repeat forever
// This example initialises the media, writes some words to the required sector, then prints
// The result from the required location.
Note
Writing bytes or words to a media sector must start from the beginning of the sector. All writes will be incremental until the media_Flush() function is executed, or the sector address rolls over to the next sector. When media_Flush() is called, any remaining bytes in the sector will be padded with 0xFF, destroying the previous contents. An attempt to use the media_SetAdd(..) function will result in the lower 9 bits being interpreted as zero. If the writing rolls over to the next sector, the media_Flush() function is issued automatically internally.
media_Flush
After writing any data to a sector, media_Flush() should be called to ensure that the current sector that is being written is correctly stored back to the media else write operations may be unpredictable.
Syntax: media_Flush();
Returns: Non-zero if OK, 0 if Failed.
Example: See the media_WriteByte(..) and media_WriteWord(..) examples.
media_Image
Displays an image from the media storage at the specified co-ordinates. The image address is previously specified with the media_SetAdd(..) or media_SetSector(...) function. If the image is shown partially off-screen, it may not be displayed correctly.
Syntax: media_Image(x, y);
| Arguments | Description |
|---|---|
| x, y | Specifies the top left position where the image will be displayed. |
Returns: None
Example
while(media_Init()==0); // wait if no SD card detected
media_SetAdd(0x0001, 0xDA00); // point to the books04 image
media_Image(10,10);
gfx_Clipping(ON); // turn off clipping to see the difference
media_Image(-12,50); // show image off screen to the left
media_Image(50, -12); // show image off screen at the top
repeat forever
// This example draws an image at several positions, showing the effects of clipping.
media_Video
Displays a video clip from the media storage device at the specified co-ordinates. The video address location in the media is previously specified with the media_SetAdd(..) or media_SetSector(...) function. If the video is shown partially off-screen, it may not be displayed correctly. Note that showing a video blocks all other processes until the video has finished showing. See the media_VideoFrame(...) functions for alternatives.
Syntax: media_Video(x, y);
| Arguments | Description |
|---|---|
| x, y | Specifies the top left position where the video clip will be displayed. |
Returns: None
Example
while(media_Init()==0); // wait if no SD card detected
media_SetAdd(0x0001, 0x3C00); // point to the 10 gear clip
media_Video(10,10);
gfx_Clipping(ON); // turn off clipping to see the difference
media_Video(-12,50); // show video off screen to the left
media_Video(50, -12); // show video off screen at the top
repeat forever
// This example plays a video clip at several positions, showing the effects of clipping.
media_VideoFrame
Displays a video from the media storage device at the specified co-ordinates. The video address is previously specified with the media_SetAdd(..) or media_SetSector(...) function. If the video is shown partially off it may not be displayed correctly. The frames can be shown in any order. This function gives you great flexibility for showing various icons from an image strip, as well as showing videos while doing other tasks.
media_VideoFrame(..) will now show error box for out of range video frames. Also, if frame is set to -1, just a rectangle will be drawn in background colour to blank an image. It applies to PmmC R29 or above.
Syntax: media_VideoFrame(x, y, frameNumber);
| Arguments | Description |
|---|---|
| x, y | Specifies the top left position where the video clip will be displayed. |
| frameNumber | Specifies the required frame to be shown. |
Returns: None
Example
var frame;
while (media_Init()==0); // wait if no SD card detected
while (media_Init()==0); // wait if no SD card detected
media_SetAdd(0x0002, 0x3C00); // point to the 10 gear image
repeat
frame := 0; // start at frame 0
repeat
media_VideoFrame(30,30, frame++); // display a frame
pause(peekB(IMAGE_DELAY)); // pause for the time given in
// the image header
until(frame == peekW(IMG_FRAME_COUNT)); // loop until we've
// shown all the frames
forever // do it forever
// This first example shows how to display frames as required while possibly doing other tasks.
Note
The frame timing (although not noticeable in this small example) is not correct as the delay commences after the image frame is shown, therefore adding the display overheads to the frame delay.
var framecount, frame, delay, colr;
frame := 0;
// show the first frame so we can get the video header info
// into the system variables, and then to our local variables.
media_VideoFrame(30,30, 0);
framecount := peekW(IMG_FRAME_COUNT); // we can now set some local
// values.
delay := peekB(IMAGE_DELAY); // get the frame count and delay
repeat
repeat
pokeW(TIMER0, delay); // set a timer
media_VideoFrame(30,30, frame++); // show next frame
gfx_MoveTo(64,35);
print([DEC2Z] frame); // print the frame number
media_VideoFrame(30,80, framecount frame); // show movie
// backwards.
gfx_MoveTo(64,85);
print([DEC2Z] framecount frame); // print the frame number
if ((frame & 3) == 0)
gfx_CircleFilled(80,20,2,colr); // a blinking circle fun
colr := colr ^ 0xF800; // alternate colour,
endif // BLACK/RED using XOR
//do more here if required
while(peekW(TIMER0)); // wait for timer to expire
until(frame == peekW(IMG_FRAME_COU NT));
frame := 0;
forever
// This second example employs a timer for the framing delay, and shows the same movie simultaneously running forward and backwards with time left for other tasks as well. A number of videos (or animated icons) can be shown simultaneously using this method.
Memory Allocation Functions
mem_alloc
Allocate a block of memory to pointer myvar. The allocated memory contains garbage but is a fast allocation.
The block must later be released with mem_Free(myvar);.
Syntax: mem_Alloc(size);
| Arguments | Description |
|---|---|
| size | Specifies the number of bytes that's allocated from the heap. |
Returns: Value is the pointer (Word) to the allocation if successful. If function fails returns a null (0).
Example
mem_AllocV
Allocate a block of memory to pointer myvar. The block of memory is filled with initial signature values.
The block starts with A5,5A then fills with incrementing number e.g.:- A5,5A,00,01,02,03...FF,00,11....
This can be helpful when debugging. The block must later be released with mem_Free(myvar).
Syntax: mem_AllocV(size);
| Arguments | Description |
|---|---|
| size | Specifies the number of bytes that's allocated from the heap. |
Returns: Value is the pointer (Word) to the allocation if successful. If function fails returns a null (0).
Example
mem_Allocz
Allocate a block of memory to pointer myvar. The block of memory is filled with zeros.
The block must later be released with mem_Free(myvar);.
Syntax: mem_Allocz(size);
| Arguments | Description |
|---|---|
| size | Specifies the number of bytes that's allocated from the heap. |
Returns: Value is the pointer to the allocation if successful. If function fails returns a null (0).
Example
mem_Realloc
The function may move the memory block to a new location, in which case the pointer to the new location is returned.
The content of the memory block is preserved up to the least of the new and old sizes, even if the block is moved.
If the new size is larger, the value of the newly allocated portion is indeterminate.
In case that ptr is NULL, the function behaves exactly as mem_Alloc(), assigning a new block of size bytes and returning a pointer to the beginning of it.
In case that the size is 0, the memory previously allocated in ptr is deallocated as if a call to mem_Free(myvar) was made, and a NULL pointer is returned.
Syntax: mem_Realloc(ptr, size);
| Arguments | Description |
|---|---|
| ptr | Specifies the new location to reallocate the memory block. |
| size | Specifies the number of bytes of the block. |
Returns: Pointer to the new object location.
Example
mem_free
The function de-allocates a block of memory previously created with mem_Alloc(...), mem_AllocV(...) or mem_AllocZ(...).
Syntax: mem_Free(allocation);
| Arguments | Description |
|---|---|
| allocation | specifies the location of memory block to free up. |
Returns: Non-zero if function is successful, 0 if the function fails.
Example
mem_Heap
Returns byte size of the largest chunk of memory available in the heap.
Syntax: mem_Heap();
Returns: The largest available byte memory chunk in the heap.
Example
mem_Set
Fill a block of memory with a byte value.
Syntax: mem_Set(ptr, char, size);
| Arguments | Description |
|---|---|
| ptr | Specifies the memory block. |
| char | Specifies the value to fill the block with. |
| size | Specifies the size of the block in Bytes. |
Returns: The pointer.
Example
var mybuf[5];
var i;
func main()
mem_Set(mybuf,0x55,5); //Only fills half of
for(i:=0;i<sizeof(mybuf);i++) //Show what is in the buffer
print(" 0x",[HEX]mybuf[i]);
next
mem_Set(mybuf,0xAA,sizeof(mybuf)*2); //Fill entire buffer
print("\n"); //New line
for(i:=0;i<sizeof(mybuf);i++)
print(" 0x",[HEX]mybuf[i]);
next
repeat
forever
endfunc
mem_Copy
Copy a word aligned block of memory from source to destination.
Syntax: mem_Copy(source, destination, count);
| Arguments | Description |
|---|---|
| source | Specifies the source memory block. |
| destination | Specifies the destination memory block. |
| count | Specifies the size of the blocks in bytes. |
Returns: Source.
Example
Note
The count is a byte count, this facilitates comparing word aligned byte arrays when using word aligned packed strings. Source can be a string constant e.g. ``` cpp myptr := mem_Copy("TEST STRING", ptr2, 12); ````
mem_Compare
Compare two blocks of memory ptr1 and ptr2.
Syntax: mem_Compare(ptr1, ptr2, count);
| Arguments | Description |
|---|---|
| ptr1 | Specifies the 1st memory block. |
| ptr2 | Specifies the 2nd memory block. |
| count | Specifies the number of bytes to compare. |
Returns:
- 0 if we have a match
- -1 if ptr1 < ptr2
- +1 if ptr2 > ptr1. (The comparison is done alphabetically)
Example
Serial (UART) Functions
setbaud
Use this function to set the required baud rate. The default Baud Rate for COM0 is 115,200 bits per second or 115,200 baud.
The default Baud Rate for COM1 is 9600 bits per second or 9600 baud.
There are pre-defined baud rate constants for most common baud rates:
| Rate / Pre-defined Constant | Baud Rate Error (%) | Actual Baud Rate |
|---|---|---|
| BAUD_110 | 0.00 | 110 |
| BAUD_300 | 0.00 | 300 |
| BAUD_600 | 0.01 | 600 |
| BAUD_1200 | 0.03 | 1200 |
| BAUD_2400 | 0.07 | 2402 |
| BAUD_4800 | 0.16 | 4808 |
| BAUD_9600 | 0.33 | 9632 |
| BAUD_14400 | 0.16 | 14423 |
| BAUD_19200 | 0.33 | 19264 |
| BAUD_31250 | 0.00 | 31250 |
| MIDI | 0.00 | 31250 |
| BAUD_38400 | 0.33 | 38527 |
| BAUD_56000 | 0.45 | 56250 |
| BAUD_57600 | 1.73 | 58594 |
| BAUD_115200 | 1.73 | 117188 |
| BAUD_128000 | 4.63 | 133929 |
| BAUD_256000 | 9.86 | 281250 |
| BAUD_300000 | 4.17 | 312500 |
| BAUD_375000 | 7.14 | 401786 |
| BAUD_500000 | 12.50 | 562500 |
| BAUD_600000 | 17.19 | 703125 |
Syntax: setbaud(rate);
| Arguments | Description |
|---|---|
| rate | Specifies the baud rate of COM0 using the baud number or pre-defined constant. |
Returns: None
Example
Note
Baud rates each have degree of accuracy for several reasons. The actual baud rate you would receive and relevant error% compared to the setting value, can be calculated.
ActualBaud is calculated using the following formula: ActualBaud = 2812500/(trunc(2812500/RequiredBaud))
Example for 115200 is, 2812500/115200 = 24.414, Trucated is 24. 2812500/37 = 117188 (rounded).
Error% therefore is % difference between 115200 and 117188, therefore 1.73%
It is desirable to only use a baud rate between 2 devices which has a difference of typically < 2%. Note both devices will have a degree of error, not just this 4D Processor, both need to be considered.
com_SetBaud
Use this function to set the required baud rate for the required Com port.
Syntax: com_SetBaud(“comport”, “baudrate/10”);
| Arguments | Description |
|---|---|
| comport | Specifies the Com port, COM0 or COM1 |
| baudrate/10 | Specifies the baud rate. |
Returns: True if BAUD rate was acceptable.
Example
stat := com_SetBaud(COM1 , 9600) // To set Com1 to 9600 BAUD rate.
if (stat)
print(“Com1 set to 9600 BAUD”);
endif
Note
Baud Rates are not always precise, and an approximate error can be seen from the setbaud() functions table on the previous page.
Baud rates each have degree of accuracy for several reasons. The actual baud rate you would receive and relevant error% compared to the setting value, can be calculated.
ActualBaud is calculated using the following formula: ActualBaud = 2812500/(trunc(2812500/RequiredBaud))
Example for 115200 is, 2812500/115200 = 24.414, Trucated is 24. 2812500/37 = 117188 (rounded).
Error% therefore is % difference between 115200 and 117188, therefore 1.73%
It is desirable to only use a baud rate between 2 devices which has a difference of typically < 2%. Note both devices will have a degree of error, not just this 4D Processor, both need to be considered.
serin
serin(): Receives a character from the Serial Port COM0.
serin1(): Receives a character from the Serial Port COM1.
serin may be buffered (refer to com_Init(..) functions). If it is desired to be able to receive the BREAK signal using buffered functions then the com_InitBrk() function must be used instead.
The transmission format is: No Parity, 1 Stop Bit, 8 Data Bits (N,8,1).
The default Baud Rate for COM0 is 115,200 bits per second or 115,200 baud.
The default Baud Rate for COM1 is 9600 bits per second or 9600 baud.
The baud rate can be changed under program control by using the setbaud(...) function.
Syntax: serin(); or serin1();
Returns: A positive value 0 to 255 for a valid character received.
-1 if no character is available.
-2 if a framing error or over-run has occurred (auto cleared).
-3 (BREAK) if a break signal is detected.
Example
var char;
char := serin(); //test the com 0 port
if (char >= 0) // if a valid character is received
process(char); // process the character
endif
serout
serout(): Transmits a single byte to the Serial Port COM0.
serout1(): Transmits a single byte to the Serial Port COM1.
The transmission format is: No Parity, 1 Stop Bit, 8 Data Bits (N,8,1).
The default Baud Rate for COM0 is 115,200 bits per second or 115,200 baud.
The default Baud Rate for COM1 is 9600 bits per second or 9600 baud.
The baud rate can be changed under program control by using the setbaud(...) function.
serout() normally blocks until the character can be transmitted, to enable serout to be non-blocking see com_TXbuffer(..).
Syntax: serout(char); or serout1(char);
| Arguments | Description |
|---|---|
| char | Specifies the data byte to be sent to the serial port. |
Returns: None
Example
com_Init
This is the initialisation function for the serial communications buffered service. Once initialised, the service runs in the background capturing and buffering serial data without the user application having to constantly poll the serial port. This frees up the application to service other tasks.
MODES OF OPERATION
- No qualifier – simple ring buffer (aka circular queue)
If the qualifier is set to zero, the buffer is continually active as a simple circular queue. Characters when received from the host are placed in the circular queue (at the 'head' of the queue) Bytes may be removed from the circular queue (from the 'tail' of the queue) using the serin() function. If the tail is the same position as the head, there are no bytes in the queue, therefore serin() will return -1, meaning no character is available, also, the com_Count() function can be read at any time to determine the number of characters that are waiting between the tail and head of the queue. If the queue is not read frequently by the application, and characters are still being sent by the host, the head will eventually catch up with the tail setting the internal COM_FULL flag (which can be read with the com_Full() function) . Any further characters from the host are now discarded, however, all the characters that were buffered up to this point are readable. This is a good way of reading a fixed size packet and not necessarily considered to be an error condition. If no characters are removed from the buffer until the COM_FULL flag (which can be read with the com_Full() function) becomes set, it is guaranteed that the bytes will be ordered in the buffer from the start position, therefore, the buffer can be treated as an array and can be read directly without using serin() at all. In the latter case, the correct action is to process the data from the buffer, re-initialise the buffer with the com_Init(..) function, or reset the buffered serial service by issuing the com_Reset() function (which will return serial reception to polled mode) , and send an acknowledgement to the host (traditionally a ACK or 6) to indicate that the application is ready to receive more data and the previous 'packet' has been dealt with, or conversely, the application may send a negative acknowledgement to indicate that some sort of error occurred, or the action could not be completed (traditionally a NAK or 16) .
If any low level errors occur during the buffering service (such as framing or over-run) the internal COM_ERROR flag will be set (which can be read with the com_Error() function). Note that the COM_FULL flag will remain latched to indicate that the buffer did become full, and is not reset (even if all the characters are read) until the com_Init(..) or com_Reset() function is issued.
- Using a qualifier
If a qualifier character is specified, after the buffer is initialised with com_Init(..) , the service will ignore all characters until the qualifier is received and only then initiate the buffer write sequence with incoming data. After that point, the behaviour is the same as above for the 'non-qualified' mode.
com_Init(buffer, bufsize, qualifier): Initialize a serial capture buffer for COM0.
com1_Init(buffer, bufsize, qualifier): Initialize a serial capture buffer for COM1.
Syntax: com_Init(buffer, bufsize, qualifier); or com1_Init(buffer, bufsize, qualifier);
| Arguments | Description |
|---|---|
| buffer | Specifies the address of a buffer used for the background buffering service. |
| bufsize | Specifies the byte size of the user array provided for the buffer (each array element holds 2 bytes). If the buffer size is zero, a buffer of 128 words (256 bytes) should be provided for automatic packet length mode (see below). |
| qualifier | Specifies the qualifying character that must be received to initiate serial data reception and buffer write. A zero (0x00) indicates no qualifier to be used. |
Returns: None
Example
com_Reset
Resets the serial communications buffered service and returns it to the default polled mode.
com_Reset() Reset COM0.
com1_Reset() Reset COM1.
Syntax: com_Reset(); or com1_Reset();
Returns: None
Example
com_Count
Can be read at any time (when in buffered communications is active) to determine the number of characters that are waiting in the buffer.
com_Count(); Charcters countr in COM0.
com1_Count(); Charcters countr in COM1.
Syntax: com_Count(); or com1_Count();
Returns: Current count of characters in the communications buffer.
Example
com_Full
If the queue is not read frequently by the application, and characters are still being sent by the host, the head will eventually catch up with the tail setting the COM_FULL flag which is read with this function. If this flag is set, any further characters from the host are discarded, however, all the characters that were buffered up to this point are readable.
Syntax: com_Full(); or com1_Full();
Returns: 1 if buffer or queue has become full, or is overflowed, else returns 0.
Example
com_Error
If any low level errors occur during the buffering service (such as framing or over-run) the internal COM_ERROR flag will be set which can be read with this function.
Syntax: com_Error(); or com1_Error();
Returns: 1 if any low level communications error occurred, else returns 0
Example
if(com_Error()) // if there were low level comms errors,
resetMySystem(); // take corrective action
endif
com_Sync
If a qualifier character is specified when using buffered communications, after the buffer is initialized with com_Init(..), the service will ignore all characters until the qualifier is received and only then initiate the buffer write sequence with incoming data. com_Sync() is called to determine if the qualifier character has been received yet.
Syntax: com_Sync(); or com1_Sync();
Returns: 1 if the qualifier character has been received, else returns 0.
Example
com_TXbuffer
Initialise a serial buffer for the COM0 or COM1 output.
The program must declare a var array as a circular buffer. When a TX buffer is declared for comms, the transmission of characters becomes non-blocking. The only time blocking will occur is if the buffer has insufficient space to accept the next character, in which case the function will wait for buffer space to become available. If the TX buffer is no longer required, just set the buffer pointer to zero, the size in this case doesn't matter and is ignored. The function can resize or reallocated to another buffer at any time. The buffer is flushed before any changes are made.
"pin" designates an IO pin to control a bidirectional control device for half duplex mode. "pin" will go HI at the start of a transmission, and will return low after the final byte is transmitted.
Once the buffer has been initialised you just continue to use serout() in the usual way, no other programming changes are required.
Syntax: com_TXbuffer(buf, bufsize, pin); or com1_TXbuffer(buf, bufsize, pin);
| Arguments | Description |
|---|---|
| buf | Specifies the address of a buffer used for the buffering service. |
| bufsize | Specifies the byte size of the user array provided for the buffer (each array element holds 2 bytes). |
| pin | Specifies the turnaround pin. If not required, just set "pin" to zero. |
Returns: None
Example
com_TXbuffer(mybuf, 1024, IO1_PIN); // set the TX buffer
com_TXbuffer(0, 0, 0); // revert to non buffered service
com_TXbufferHold
This function is used in conjunction with com_TXbuffer(...).
It is often necessary to hold off sending serial characters until a complete frame or packet has been built in the output buffer. com_TXbufferHold(ON) is used for this, to stop the buffer being sent while it is being loaded. Normally, when using buffered comms, the transmit process will begin immediately. This is fine unless you are trying to assemble a packet.
To build a packet and send it later, issue a com_TXbufferHold(ON); build the packet, when packet is ready, issuing com_TXbufferHold(OFF);, will release the buffer to the com port.
Also, if using com_TXemptyEvent, erroneous empty events will occur as the transmit buffer is constantly trying to empty while you are busy trying to fill it.
Also refer to the pin control for com_TXbuffer(..) function.
Syntax: com_TXbufferHold(state); or com1_TXbufferHold(state);
| Arguments | Description |
|---|---|
| state | Specifies the state of the buffer used for the buffering service. |
Returns:
- Buffer count when called with argument of 1, for example com_TXbufferHold(ON)
- 0 when argument is zero, e.g. com_TXbufferHold(OFF)
Example: Refer to the com_TXemptyEvent(functionAddress) example.
Note
If you fill the buffer whilst it is held comms error 4 will be set and the data written will be lost.
com_TXcount
Return count of characters remaining in COM0 or COM1 transmit buffer that was previously allocated with com_TXbuffer(..); or com1_TXbuffer(..);.
Syntax: com_TXcount(); or com1_TXcount();
Returns: Count of characters.
Example
com_TXemptyEvent
If a comms TX buffer that was previously allocated with com_TXbuffer(..) or com1_TXbuffer(..). This function can be used to set up a function to be called when the COM0 or COM1 TX buffer is empty.
This is useful for either reloading the TX buffer, setting or clearing a pin to change the direction of e.g. a RS485 line driver, or any other form of traffic control. The event function must not have any parameters. To disable the event, simply call com_TXemptyEvent(0) or com1_TXemptyEvent(0).
com_TXbuffer(..) or com1_TXbuffer(..) also resets any active event.
Syntax: com_TXemptyEvent(functionAddress); or com1_TXemptyEvent(functionAddress);
| Arguments | Description |
|---|---|
| functionAddress | Address of the event Function to be queued when COM0 or COM1 TX buffer empty. |
Returns: Any previous event function address or zero if there was no previous function.
Example
#platform "uLCD-32PT_GFX2"
/*************************************************
* Description: buffered TX service
* Use Workshop terminal at 9600 baud to see result
* Example of Buffered TX service vs Non buffered
* Also explains the use of COMMS events
*
* NB Program must be written to flash so
* the Workshop Terminal can be used.
*
**************************************************/
var combuf[220]; // buffer for up to 440 bytes
// run a timer event while we are doing comms
func T7Service()
var private colour := 0xF800;
colour ^= 0xF800;
gfx_RectangleFilled(50,200,80,220,colour);
sys_SetTimer(TIMER7, 200);
endfunc
// event to capture the buffer empty event
func bufEmpty()
com_TXbuffer(0, 0, IO1_PIN); // done with the buffer, release it
print("\n\nHELLO WORLD, I'M EMPTY ",com_TXcount(),"\n");
endfunc
func main()
var n, r, D, fh;
sys_SetTimerEvent(TIMER7,T7Service); // run a timer event
sys_SetTimer(TIMER7, 150);
com_TXemptyEvent(bufEmpty); // set to capture buffer empty event
setbaud(BAUD_9600);
txt_Set(TEXT_OPACITY, OPAQUE);
repeat
gfx_Cls();
txt_MoveCursor(3,1); // reset cursor to line 3, column 2
print("Send 440 chars non-buffered\n");
pokeW(SYSTEM_TIMER_LO, 0); // reset timer
// note that 440 chars at 9600 baud takes approx 453msec
for(n:=0; n<10; n++)
to(COM0); putstr("The quick brown fox jumps over the lazy dog\n"); // 44 chars
next
print("took ",peekW(SYSTEM_TIMER_LO),"Msec\n\n");
// time spent blocking is only approx 1msec
com_TXbuffer(combuf, 440,IO1_PIN);// set up the TX buffer
com_TXbufferHold(ON); // hold the TX buffer til ready
// note that here the time is only approx 1msec overhead due to buffering.
print("Send 440 chars buffered\n");
pokeW(SYSTEM_TIMER_LO, 0); // reset timer
for(n:=0; n<10; n++)
to(COM0); putstr("THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG\n"); // 44 chars
next
print("took ",peekW(SYSTEM_TIMER_LO),"Msec\n\n");
// time spent blocking is only approx 1msec
// demonstrate how to modify a prepared comms buffer that is still being held
to(combuf); print("MY CONTENTS HAVE BEEN CHANGED");
to(combuf+50); print("*** AND CHANGED HERE TOO ***");
combuf[218] := 'CA'; // the last 'DOG' changed here
combuf[219] := 'T\n'; // the last 'DOG' changed here
// now we are ready to send to buffer
n := com_TXbufferHold(OFF); // release TX buffer
print("TXBuffer is holding ", n, " chars\n");
// show how many characters were in the buffer
// watch the buffer empty
repeat
print("TX count = ", [DEC5ZB] n := com_TXcount(),"\r"); // watch the count as the buffer empties
until(!n);
print("\n\nTX Empty");
com_TXbuffer(0, 0, IO1_PIN); // done with the buffer, release it
sys_SetTimer(TIMER0, 3000); // pause for 3 seconds, non blocking
while(peekW(TMR0));
forever // do it forever
// com_TXbuffer(0, 0, 0); // if done with the pin, must release it
endfunc
Sound Control Functions
snd_Volume
Set the sound playback volume. Var must be in the range from 8 (min volume) to 127 (max volume). If var is less than 8, volume is set to 8, and if var > 127 it is set to 127.
Syntax: snd_Volume(var);
| Arguments | Description |
|---|---|
| var | sound playback volume. |
Returns: None
Example
snd_Pitch
Sets the samples playback rate to a different frequency. Setting pitch to zero restores the original sample rate.
Syntax: snd_Pitch(pitch)
| Arguments | Description |
|---|---|
| pitch | Sample's playback rate. Minimum is 4KHz. Range is, 4000 – 65535. |
Returns: Sample's original sample rate.
Example
snd_BufSize
Specify the memory chunk size for the wavefile buffer, default size 1024 bytes. Depending on the sample size, memory constraints, and the sample quality, it may be beneficial to change the buffer size from the default size of 1024 bytes.
This function is for control of a wav buffer, see the file_PlayWAV(..) function.
Syntax: snd_BufSize(var);
| Arguments | Description |
|---|---|
| var | Specifies the buffer size. 0 = 1024 bytes (default) 1 = 2048 bytes 2 = 4096 bytes 3 = 8192 bytes |
Returns: None
Example
snd_Stop
Stop any sound that is currently playing, releasing buffers and closing any open wav file. This function is for control of a wav buffer, see the file_PlayWAV(..) function.
Syntax: snd_Stop();
Returns: None
Example
snd_Pause
Pause any sound that is currently playing, does nothing until sound is resumed with snd_Continue().
This function is for control of a wav buffer, see the file_PlayWAV(..) function.
Syntax: snd_Pause();
Returns: None
Example
snd_Continue
Resume any sound that is currently paused by snd_Pause.
This function is for control of a wav buffer, see the file_PlayWAV(..) function.
Syntax: snd_Continue();
Returns: None
Example
snd_Playing
Returns 0 if sound has finished playing, else return number of 512 byte blocks to go.
This function is for control of a wav buffer, see the file_PlayWAV(..) function.
Syntax: snd_Playing();
Returns: Number of 512 byte blocks to go.
Example
SPI Control Functions
The SPI functions in this section apply to any general purpose SPI device.
spi_Init
Sets up the PICASO SPI port to communicate with SPI devices. See the example in section spi_Read().
Syntax: spi_Init(speed, input_mode, output_mode);
| Arguments | Description |
|---|---|
| speed | Sets the speed of the SPI port. |
| input_mode | Sets the input mode of the SPI port. See diagram below. |
| output_mode | Sets the output mode of the SPI port. See diagram below. |
Returns: None
Example
spi_Init(SPI_FAST,0); // init SPI at maximum speed for 16MB Flash
spi_Init(SPI_SLOW,SPI_ADDRESS_MODE4); // init SPI at Slow speed for 32MB
Note
The SPI functions in this section are not necessary when using the memory card or serial flash chips interfaced to the SPI port. The SPI functions in this section are relevant to those devices other than the memory card and the serial flash chip used for media access.
spi_Read
This function allows a raw unadorned byte read from the SPI device.
Syntax: spi_Read();
Returns: A single data byte from the SPI device.
Example
var result;
spi_Init(SPI_SLOW, RXMODE_0, CKMODE_0);
print("Hello World\n") ; // replace with your code
//...
spi_Write(0x40); // x_Accel Request
result := spi_Read();
print("result: ", result);
Note
The Chip Select line (SDCS) is lowered automatically.
spi_Write
This function allows a raw unadorned byte write to the SPI device.
Syntax: spi_Write(byte);
| Arguments | Description |
|---|---|
| byte | Specifies the data byte to be sent to the SPI device. |
Returns: None
Example: See the example in section spi_Read().
Note
The Chip Select line (SDCS) is lowered automatically.
spi_Disable
This function raises the Chip Select (SDCS) line of the SPI device, disabling it from further activity. The CS line will be automatically lowered next time the SPI functions spi_Read() or spi_Write(...) are used, and also by the action of any media_functions.
Syntax: spi_Disable();
Returns: None
String Class Functions
str_Ptr
Return a byte pointer to a word region.
Syntax: str_Ptr(&var);
| Arguments | Description |
|---|---|
| var | Pointer to string buffer. |
Returns: Value is the byte pointer to string buffer.
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
var n;
var vars[3]; // for our results
func main()
to(buffer); print("0x1234 0b10011001 12345 abacus");
p := str_Ptr(buffer); //raise string pointer for the string functions
while(str_GetW(&p, &vars[n++]) != 0); // read all the numbers till we get a non number
print(vars[0],"\n", vars[1],"\n", vars[2],"\n"); // print them out
endfunc
str_GetD
Convert number in a string to DWORD (myvar[2]).
Syntax: str_GetD(&ptr, &var);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string. |
| var | Destination for our result. |
Returns: TRUE if function succeeds, advancing ptr.
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
var n;
var vars[6]; // for our results
func main()
to(buffer); print("100000 200000 98765432 abacus");
p := str_Ptr(buffer); // raise a string pointer so we can use the
// string functions
while(str_GetD(&p, &vars[n]) != 0) n:=n+2; //read all the numbers till we get a non number
print( [HEX4] vars[1], ":" , [HEX4] vars[0], "\n" );
// show the longs as hex numbers
print( [HEX4] vars[3], ":" , [HEX4] vars[2], "\n" );
print( [HEX4] vars[5], ":" , [HEX4] vars[4], "\n" );
endfunc
Note
The address of the pointer must be passed so the function can advance it if required.
str_GetW
Convert number in a string to WORD (myvar).
Syntax: str_GetW(&ptr, &var);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string. |
| var | Destination for our result. |
Returns: TRUE if function succeeds, advancing ptr.
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
var n;
var vars[3]; // for our results
func main()
to(buffer); print("0x1234 0b10011001 12345 abacus");
p := str_Ptr(buffer); // raise a string pointer so we can use the
// string functions
while(str_GetW(&p, &vars[n++]) != 0); // read all the numbers till we get a non number
print(vars[0],"\n", vars[1],"\n", vars[2],"\n"); // print them out
str_Printf (&p, "%s\n" ); // numbers extracted, now just print remainder of string
endfunc
Note
The address of the pointer must be passed so the function can advance it if required.
str_GetHexW
Convert hex number in a string to WORD (myvar).
This function is for extracting 'raw' hex words with no "0x" prefix.
Syntax: str_GetHexW(&ptr, &var);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string. |
| var | Destination for our result. |
Returns: TRUE if function succeeds, advancing ptr.
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
var n;
var vars[4]; // for our results
func main()
to(buffer); print("1234 5678 9 ABCD");
p := str_Ptr(buffer); // raise a string pointer so we can use the string functions
while(str_GetHexW(&p, &vars[n++]) != 0); // read all the hex numbers till we get a non number
print(vars[0],"\n", vars[1],"\n" , vars[2],"\n", vars[3],"\n");
endfunc
Note
The address of the pointer must be passed so the function can advance it if required.
str_GetC
Get next valid ascii char in a string to myvar.
The function returns 0 if end of string reached. Used for extracting single characters from a string.
Syntax: str_GetC(&ptr, &var);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string. |
| var | Destination for our result. |
Returns: TRUE if function succeeds, advancing ptr.
Example
var p; // string pointer
var n;
var char;
var buffer[100]; // 200 character buffer for a source string
func main()
to(buffer); print("Quick Brown Fox");
p := str_Ptr(buffer); // raise a string pointer so we can use the string functions
while(str_GetC(&p, &char))
print("p=",p," char is", [CHR] char); // print characters
wend
print("End of string");
endfunc
Note
The address of the pointer must be passed so the function can advance it if required.
str_GetByte
Get a byte to myvar. Similar to "PEEKB" in basic.
It is not necessary for byte pointer ptr to be word aligned.
Syntax: str_GetByte(ptr);
| Arguments | Description |
|---|---|
| ptr | Address of byte array or string. |
Returns: The byte value at pointer location.
Example
var buffer[100]; // 200 character buffer for a source string
var n, p;
func main()
to(buffer); print("Testing 1 2 3");
p := str_Ptr(buffer); // get a byte pointer from a word region
n := 0;
while (n <= str_Length(buffer))
print( [HEX2] str_GetByte(p + n++)," "); // print all the chars hex values
wend
endfunc
str_GetWord
Get a word to myvar. Similar to "PEEKW" in basic.
It is not necessary for byte pointer ptr to be word aligned.
Syntax: str_GetWord(ptr);
| Arguments | Description |
|---|---|
| ptr | Byte pointer. |
Returns: The word at pointer location.
Example
var p; // string pointer
var buffer[10]; // array for 20 bytes
func main()
p := str_Ptr (buffer); // raise a string pointer
str_PutWord (p+3, 100); // 'poke' the array
str_PutWord (p+9, 200);
str_PutWord (p+12, 400);
print(str_GetWord( p + 3), "\n" ); // 'peek' the array
print( str_GetWord( p + 9),"\n" );
print( str_GetWord( p + 12), "\n" );
endfunc
str_PutByte
Put a byte value into a string buffer at ptr. Similar to "POKEB" in basic. It is not necessary for byte pointer ptr to be word aligned.
Syntax: str_PutByte(ptr, val);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string. |
| val | Byte value to insert. |
Returns: None
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
func main()
p := str_Ptr(buffer); // raise a string pointer so we can use the
// string functions
str_PutByte(p + 3, 'A'); // store some values
str_PutByte(p + 4, 'B'); // store some values
str_PutByte(p + 5, 'C'); // store some values
str_PutByte(p + 6, 'D'); // store some values
str_PutByte(p + 7, 0); // string terminator
print(vars[0],"\n", vars[1],"\n", vars[2],"\n"); // print them out
p := p + 3; // offset to where we placed the chars
str_Printf(&p, "%s\n"); // print the result
// nb, also, understand that the core print service
// assumes a word aligned address so it starts at pos 4
// print( [STR] &buffer[2]);
endfunc
str_PutWord
Put a word value into a byte buffer at ptr, similar to "POKEW" in basic. It is not necessary for byte pointer ptr to be word aligned.
Syntax: str_PutWord(ptr, val);
| Arguments | Description |
|---|---|
| ptr | Byte pointer. |
| val | Value to store. |
Returns: None
Example
var p; // string pointer
var numbers[10]; // array for 20 bytes
func main()
p := str_Ptr (numbers); // raise a string pointer
str_PutWord (p+3, 100); // 'poke' the array with some numbers
str_PutWord (p+9, 200);
str_PutWord (p+12, 400);
print( str_GetWord( p + 3), "\n" ); // 'peek' the array
print( str_GetWord( p + 9), "\n" );
print( str_GetWord( p + 12), "\n" );
endfunc
str_Match
Case Sensitive match. Compares the string at position ptr in a string buffer to the string str, skipping over any leading spaces if required. If a match occurs, ptr is advanced to the first position past the match, else ptr is not altered.
Syntax: str_Match(&ptr, *str);
| Arguments | Description |
|---|---|
| ptr | Address of byte pointer to string buffer. |
| str | Pointer string to match. |
Returns: 0 if no match, else advance ptr to the next position after the match and returns a pointer to the match position.
Example
var buffer[100]; // 200 character buffer for a source string
var p, q; // string pointers
var n;
func main()
to(buffer); print( " volts 240 " ); // string to parse
p := str_Ptr(buffer); // string pointer to be used with string functions
q := p;
// match the start of the string with "volts"
if ( n := str_Match( &p, "volts" ) )
str_Printf( &p, "%s\n" ); // print remainder of string
else
print ( "not found\n" );
endif
print ( "startpos=" , q , "\nfindpos=" , n , "\nendpos=" , p );
repeat
forever
endfunc
Note
The address of the pointer must be passed so the function can advance it if required.
str_MatchI
Case Insensitive match. Compares the string at position ptr in a string buffer to the string str, skipping over any leading spaces if required. If a match occurs, ptr is advanced to the first position past the match, else ptr is not altered.
Syntax: str_MatchI(&ptr, *str);
| Arguments | Description |
|---|---|
| ptr | Address of the byte pointer to string buffer. |
| str | Pointer string to match. |
Returns: 0 if no match, else advance ptr to the next position after the match and returns a pointer to the match position.
Example
var buffer[100]; // 200 character buffer for a source string
var p, q; // string pointers
var n;
func main()
// string to parse
to(buffer); print( "The sun rises in the East" );
p := str_Ptr(buffer); // string pointer to be used with string functions
q := p;
// Will match if the string starts with "The", or "the"
if ( n := str_MatchI( &p, "the" ) )
str_Printf ( &p, "%s\n" ); // print remainder of string
else
print ( "not found\n" );
endif
print ( "startpos=" , q , "\nfindpos=" , n , "\nendpos=" , p );
repeat
forever
endfunc
Note
The address of the pointer must be passed so the function can advance it if required.
str_Find
Case Sensitive. Given the address of a pointer to a source string as the first argument, and a pointer to a test string as the second argument, attempts to find the position of the matching string in the source string. The test is performed with case sensitivity.
Syntax: str_Find(&ptr, *str);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string buffer. |
| str | String to find. |
Returns: 0 if not found. Returns the address of the first character of the match if successful.
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
var n;
var strings[4]; // for our test strings
func main()
txt_Set ( FONT_ID, FONT2 );
strings[0] := "useful" ;
strings[1] := "string" ;
strings[2] := "way" ;
strings[3] := "class" ;
to(buffer); print( "and by the way, the string class is rather useful " );
// raise a string pointer so we can use the string functions
p := str_Ptr(buffer);
// offset into the buffer a little so we don't see word "way"
p := p + 13;
print( "p=" , p , "\n\n" ); // show the start point of our search
n := 0;
while ( n < 4 )
print( "\\"" , [STR] strings[n] , "\" is at pos " , str_Find( &p, strings[n++] ) , "\n" );
wend
//note that p is unchanged
print ( "\nNOTE: p is unchanged, p=" , p );
repeat
forever
endfunc
Note
The pointer ptr is not altered.
str_FindI
Case Insensitive. Given the address of a pointer to a source string as the first argument, and a pointer to a test string as the second argument, attempts to find the position of the matching string in the source string. The test is performed with case insensitivity, e.g. upper and lower case chars are accepted.
Syntax: str_FindI(&ptr, *str);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to string buffer. |
| str | String to find. |
Returns: 0 if not found. Returns the address of the first character of the match if successful.
Example
var buffer[100]; // 200 character buffer for a source string
var p; // string pointer
var n;
var strings[4]; // for our test strings
func main()
txt_Set ( FONT_ID, FONT2 );
strings[0] := "USEFUL" ;
strings[1] := "string" ;
strings[2] := "way" ;
strings[3] := "class" ;
to(buffer); print ( "and by the way, the String Class is rather useful " );
// raise a string pointer so we can use the string functions
p := str_Ptr(buffer);
// offset into the buffer a little so we don't see word "way"
p := p + 13;
// show the start point of our search
print( "p=" , p , "\n\n" );
n := 0;
while ( n < 4 )
print( "\"" , [STR] strings[n] , "\" is at pos " , str_FindI(&p , strings[n++] ) ,"\n" );
wend
//note that p is unchanged
print ( "\nNOTE: p is unchanged, p=" , p );
repeat
forever
endfunc
Note
The pointer ptr is not altered.
str_Length
Returns the length of a string excluding terminator.
Syntax: str_Length(ptr);
| Arguments | Description |
|---|---|
| ptr | Pointer to string buffer. |
Returns: String length.
Example
var a;
var b;
var c[40]; // 80 character buffer for a source string
var pa, pc; //These will be String pointers to a and c[]
func main()
a := mem_Alloc( 200 ); // allocate a dynamic buffer full of random data
mem_Set (a, 'X', 200 ); // fill it full of 'X's
pa := str_Ptr(a); // raise a string pointer
str_PutByte(pa+20,0); // Now stick a string terminator in the array
// Change the 20 to be between 0 and 199
b := "A string constant" ; // b is a pointer to a string constant
to (c); print ( "An 'ASCIIZ' string is terminated with a zero" );
pc := str_Ptr(c); // raise a string pointer so we can use the string functions
print ("a length:", str_Length(pa), "\n"); // show length of the dynamic buffer
print ("b length:", str_Length(b), "\n"); // show length of the static string
print ("c length:", str_Length(pc), "\n"); // show length of the 're-directed' string
mem_Free (a); // test is over, free up the memory
repeat
forever
endfunc
str_Printf
This function prints a formatted string from elements derived from a structured byte region. There is only one input argument, the byte region pointer ptr which is automatically advanced as the format specifier string is processed. The format string is similar to the C language, however, there are a few differences, including the addition of the indirection token * (asterix).
Format Specifiers:
| format | Description |
|---|---|
| %c | character |
| %s | string of characters |
| %d | signed decimal |
| %ld | long decimal |
| %u | unsigned decimal |
| %lu | long unsigned decimal |
| %x | hex byte |
| %X | hex word |
| %lX | hex long |
| %b | binary word |
| %lb | long binary word |
(*) indirection prefix (placed after '%' to specify indirect addressing)
(number) width description (use between '%' and format specifier to set the field width).
Syntax: str_Printf(&ptr, *format);
| Arguments | Description |
|---|---|
| ptr | Byte pointer to the input data (structure). |
| format | Format string. Check the format specifiers above. |
Returns: The position of last extraction point. This is useful for processing by other string functions.
Example
var buffer[100]; // 200 character buffer for a source string
var p, q; // string pointers
var n;
var m[20]; // for our structure example
var format; // a pointer to a format string
func main()
var k;
// string print example
to (buffer); print ( "\nHELLO WORLD" );
q := str_Ptr (buffer); // raise a string pointer so we can use the string functions
p := q;
str_Printf ( &p , "%8s" ); // only prints first 8 characters of string
putch ('\n'); // new line
p := q;
k := str_Printf ( &p , "%04s" ); // prints 4 leading spaces before string
putch ('\n'); // new line
print ( k ); // if required, the return value points to the last
// source position and is returned for processing by other string function
// print structure elements example, make a demo structure
n := 0;
m[n++] := "Mrs Smith" ;
m[n++] := 200 ;
m[n++] := 300 ;
m[n++] := 0xAA55 ;
m[n++] := 500 ;
// make a demo format control string
format := "%*s\n%d\n%d\n%016b\n%04X" ; // format string for printing structure m
// print the structure in the required format
p := str_Ptr (m); // point to structure m
str_Printf (&p, format); // use the format string to print the structure
endfunc
Note
- The address of the pointer must be passed so the function can advance it as required.
- The format specifier string can be a string pointer, allowing dynamic construction of the printing format.
- If (number) is preceded by 0, the result is Left-pads with zeroes (0) instead of spaces.
str_Cat
Appends a copy of the source string to the destination string. The terminating null character in destination is overwritten by the first character of source, and a new null-character is appended at the end of the new string formed by the concatenation of both in destination.
Syntax: str_Cat(&destination, &source);
| Arguments | Description |
|---|---|
| destination | Destination string address. |
| source | Source string address. |
Returns: Pointer to the destination.
Example
var buf[100]; // 200 character buffer for a source string
func main()
var p ;
to(buf) ;
print("Hello ") ;
p := str_Ptr(buf) ;
str_Cat(p,"There"); // Will append "There" to the end of buf
print([STR] buf) ;
repeat
forever
endfunc
str_CatN
The number of characters copied is limited by "count". The terminating null character in destination is overwritten by the first character of source, and a new null-character is appended at the end of the new string formed by the concatenation of both in destination.
Syntax: str_CatN(&ptr, str, count);
| Arguments | Description |
|---|---|
| ptr | Destination string address. |
| str | Source string address. |
| count | Number of characters to be concatenated. |
Returns: Pointer to the destination.
Example
var buf[100]; // 200 character buffer for a source string
func main()
var p ;
to(buf) ;
print("Sun ") ;
p := str_Ptr(buf) ;
str_CatN(p,"Monday",3); // Concatenate "Mon" to the end of buf
print([STR] buf) ;
repeat
forever
endfunc
str_ByteMove
Copy bytes from "src" to "dest", stopping only when "count" is exhausted. No terminator is appended, it is purely a byte copy, and any zeroes encountered will also be copied.
Syntax: str_ByteMove(src, dest, count);
| Arguments | Description |
|---|---|
| src | Points to byte aligned source. |
| dest | Points to byte aligned destination. |
| count | Number of bytes to transfer. |
Returns: A pointer to the end of the destination (which is "dest" + "count").
Example
var src, dest, mybuf1[10], mybuf2[10]; // string pointers and two 20 byte buffers
to(mybuf1); putstr("TESTING 123");
src := strPtr(mybuf1);
dest := str_Ptr(mybuf2);
src += 6; // move src pointer to "G 123"
str_ByteMove(src, dest, 6); // move to second buffer (including the zero terminator)
putstr(mybuf2); // print result
nextpos := str_ByteMove(s, d, 100);
str_Copy
Copy a string from "src" to "dest", stopping only when the end of source string "src" is encountered (0x00 terminator). The terminator is always appended, even if "src" is an empty string.
Syntax: str_Copy(dest, src);
| Arguments | Description |
|---|---|
| dest | Points to byte aligned destination. |
| src | Points to byte aligned source. |
Returns: A pointer to the 0x00 string terminator at the end of "dest" (which is "dest" + str_Length(src); ).
Example
str_CopyN
Copy a string from "src" to "dest", stopping only when "count" is exhausted, or end of source string "str" is encountered (0x00 string terminator). The terminator is always appended, even if "count" is zero, or "src" is a null string.
Syntax: str_CopyN(dest, src, count);
| Arguments | Description |
|---|---|
| dest | Points to byte aligned destination. |
| src | Points to byte aligned source. |
| count | Maximum number of bytes to copy. |
Returns: A pointer to the 0x00 string terminator at the end of "dest" (which is "dest" + str_Length(src); ).
Example
System Memory Functions
peekW
This function returns the 16 bit value that is stored at address.
Syntax: peekW(address);
| Arguments | Description |
|---|---|
| address | The address of a memory word. The address is usually a pre-defined system register address constant, (see the address constants for all the system word sized registers in System Register Memory). |
Returns: The 16-bit value stored at address.
Example
var myvar;
myvar := peekW(SYSTEM_TIMER_LO);
// This example places the low word of the 32-bit system timer in myvar.
pokeW
This function writes a 16-bit value to a location specified by address.
Syntax: pokeW(address, word_value);
| Arguments | Description |
|---|---|
| Address | The address of a memory word. The address is usually a pre-defined system register address constant, (see the address constants for all the system word sized registers in System Register Memory). |
| word_value | The 16-bit word_value will be stored at address. |
Returns: TRUE if poke address was a legal address (usually ignored).
Example
Text and String Functions
txt_MoveCursor
Moves the text cursor to a screen position set by line and column parameters. The line and column position is calculated, based on the size and scaling factor for the currently selected font. When text is outputted to screen it will be displayed from this position. The text position could also be set with gfx_MoveTo(...); if required to set the text position to an exact pixel location. Note that lines and columns start from 0, so line 0, column 0 is the top left corner of the display.
Syntax: txt_MoveCursor(line, column);
| Arguments | Description |
|---|---|
| line | Holds a positive value for the required line position. |
| column | Holds a positive value for the required column position. |
Returns: None
Example
putch
putch prints single characters to the current output stream, usually the display.
Syntax: putch(char);
| Arguments | Description |
|---|---|
| char | Holds a positive value for the required character. |
Returns: None
Example
var v;
v := 0x39;
putch(v); // print the number 9 to the current display location
putch('\n'); // newline
putstr
putstr prints a string to the current output stream, usually the display. The argument can be a string constant, a pointer to a string, a pointer to an array, or a pointer to a data statement.
A string constant is automatically terminated with a zero.
A string in a data statement is not automatically terminated with a zero.
All variables in 4DGL are 16bit, if an array is used for holding 8-bit characters; each array element packs 1 or 2 characters.
Syntax: putstr(pointer);
| Arguments | Description |
|---|---|
| string | A string constant or pointer to a string. |
Returns: The pointer to the item that was printed.
Example
// Example #3 printing strings from data table
#DATA
byte message "Week",0
word days sun,mon,tue,wed,thu,fr i,sat // pointers to data items
byte sun "Sunday\n 0"
byte mon "Monday\n 0"
byte tue "Tuesday\n 0"
byte wed "Wednesday\n 0"
byte thu "Thursday\n 0"
byte fri "Friday\n 0"
byte sat "Saturday\n 0"
#END
var n;
n:=0;
while(n < 7)
putstr(days[n++]); // print the days
wend
putnum
putnum prints a 16bit number in various formats to the current output stream, usually the display.
Number formatting bits supplied by format
Pre-Defined format constant quick reference
| DEC | DECZ | DECZB |
| DEC1 | DEC1Z | DEC1ZB |
| DEC2 | DEC2Z | DEC2ZB |
| DEC3 | DEC3Z | DEC3ZB |
| DEC4 | DEC4Z | DEC4ZB |
| DEC5 | DEC5Z | DEC5ZB |
| UDEC | UDECZ | UDECZB |
| UDEC1 | UDEC1Z | UDEC1ZB |
| UDEC2 | UDEC2Z | UDEC2ZB |
| UDEC3 | UDEC3Z | UDEC3ZB |
| UDEC4 | UDEC4Z | UDEC4ZB |
| UDEC5 | UDEC5Z | UDEC5ZB |
| HEX | HEXZ | HEXZB |
| HEX1 | HEX1Z | HEX1ZB |
| HEX2 | HEX2Z | HEX2ZB |
| HEX3 | HEX3Z | HEX3ZB |
| HEX4 | HEX4Z | HEX4ZB |
| BIN | BINZ | BINZB |
| BIN1 | BIN1Z | BIN1ZB |
| BIN2 | BIN2Z | BIN2ZB |
| BIN3 | BIN3Z | BIN3ZB |
| BIN4 | BIN4Z | BIN4ZB |
| BIN5 | BIN5Z | BIN5ZB |
| BIN6 | BIN6Z | BIN6ZB |
| BIN7 | BIN7Z | BIN7ZB |
| BIN8 | BIN8Z | BIN8ZB |
| BIN9 | BIN9Z | BIN9ZB |
| BIN10 | BIN10Z | BIN10ZB |
| BIN11 | BIN11Z | BIN11ZB |
| BIN12 | BIN12Z | BIN12ZB |
| BIN13 | BIN13Z | BIN13ZB |
| BIN14 | BIN14Z | BIN14ZB |
| BIN15 | BIN15Z | BIN15ZB |
| BIN16 | BIN16Z | BIN16ZB |
Syntax: putnum(format, value);
| Arguments | Description |
|---|---|
| format | A constant that specifies the number format. |
| value | The number to be printed. |
Returns: The default width of the numeric field (digit count), usually ignored.
Example
var v;
v := 05678;
putnum(HEX, v); // print the number as hex 4 digits
putnum(BIN, v); // print the number as binary 16 digits
4DGL has a versatile print(...) statement for formatting numbers and strings.
In its simplest form, print will simply print a number as can be seen below:
myvar := 100;
print(myvar);
// This will print **100** to the current output device (usually the display in TEXT mode).
Note
If you wish to add a string anywhere within a print(...) statement, just place a quoted string expression and you will be able to mix strings and numbers in a variety of formats. See the following example.
(*) Refer the table in putnum(..) for all the numeric representations available.
The print(...) statement will accept directives passed in square brackets to make it print in various ways,
for instance, if you wish to print a number in 4 digit hex, use the [HEX4] directive placed in front
of the variable to be displayed within the print statement. See the following example.
Note
There are 2 print directives that are not part of the numeric set and will be explained separately. These are the [STR] and [CHR] directives.
The [STR] directive expects a string pointer to follow:
s := "Hello World"; // assign a string constant to s
print("Var 's' points to a string constant at address", s ," which is", [STR] s);
The [CHR] directive prints the character value of a variable.
also
Note
You can freely mix string pointers, strings, variables and expressions within a print statement.
print(...) can also use the to(...) function to redirect it's output to a different output device
other than the screen using the function (refer to the to(...) statement for further examples).
Syntax: print(...);
Returns: None
Example
#platform "uOLED-32028-P1_GFX2"
/////////////////////
// DATA STATEMENT //
/////////////////////
#DATA
word myData
myString1, Bert, Fred, main, myString2, baud, barney,
0x1111,0x2222,0x3333,0x4444
byte myString1 "Data String OK\n\n",0
byte myString2 "\"(and forward referenced!)\"\n\n",0
word baud 150,300,600,1200,2400,9600
#END
// this constant is a forward reference
#constant barney 9876
func Fred(var str)
print("string = ", [STR] str);
endfunc
func Bert(var p1, var p2, var p3)
print("hello from Bert\np1=",p1,"\np2=",p2, "\np3=",p3,"\n");
return "Bert was here\n";
endfunc
func main()
var fn; // a variable for a handle for the function
txt_Set(FONT_ID, FONT 1);
fn := myData[1]; //Get function pointer from data statement index
print( [STR] fn(100,200,300) );
// use it in a statement to prove engine ok
fn := myData[2]; //Get function pointer from data statement index
fn("ABC\n"); // execute the function
// just shows where main lives
print("\naddress of main = code[", myData[3],"]\n\n");
// remember a var can be a handle, variable, pointer or vector
print( [STR] myData[0]); // pointer table data reference
print( [STR] myData[4]);
repeat forever
endfunc
to
to() sends the printed output to destinations other than the screen. Normally, print just sends its output to the display in TEXT mode which is the default, however, the output from print can be sent to 'streams', e.g. – COM0 or COM1, an open FAT16 file with DSK, to raw media with MDA (media), or to the I2C ports with I2C.
The to(...) function can also stream to a memory array . Note that once the to(...) function has taken effect, the stream reverts back to the default stream which is TEXT as soon as putch, putstr, putnum, print, or str_Printf has completed its action.
The APPEND argument is used to append the printed output to the same place as the previous redirection. This is most useful for building string arrays, or adding sequential data to a media stream.
| Predefined Name | Constant | putch, putstr, putnum, print, str_Printf redirection |
|---|---|---|
| APPEND | 0x0000 | Output is appended to user array if previous redirection was to an array. |
| TEXT | 0xF801 | Output is directed to the screen (default). |
| DSK | 0xF802 | Output is directed to the most recently open file that has been opened in write mode. |
| COM0 | 0xF804 | Output is redirected to the COM0 (default serial) port. |
| COM1 | 0xFF05 | Output is redirected to the COM1 (auxiliary serial) port. |
| I2C | 0xF820 | Output is directed to the I2C port. |
| MDA | 0xF840 | Output is directed to the SD/SDHC or FLASH media. |
| (memory pointer) | Array Address | Output is redirect to the memory pointer argument. |
Warning
Becareful writing to a FAT16 formatted card without checking legal partitioned else the disk formatting will be destroyed.
Syntax: to(outstream);
| Arguments | Description |
|---|---|
| outstream | A variable or constant specifying the destination for the putch, putstr, putnum, print and str_Printf functions. |
Returns: None
Example
// Example #1 putstr redirection
var buf[10]; // a buffer that will hold up to 20 bytes/chars
var s; // a var for use as a pointer
to(buf); putstr("ONE "); // redirect putstr to the buffer
to(APPEND); putstr("TWO "); // and add a couple more items
to(APPEND); putstr("THREE\n");
putstr(buf); // print the result to the display
while (media_Init()==0); // wait if no SD/SDHC card detected
media_SetSector(0, 2); // at sector 2
//media_SetAdd(0, 1024); // (alternatively, use media_SetAdd(), lower 9 bits ignored).
to(MDA); putstr("Hello World"); // now write a ascii test string
media_WriteByte('A'); // write a further 3 bytes
media_WriteByte('B');
media_WriteByte('C');
to(MDA); putstr(buf); // write the buffer we prepared earlier
media_WriteByte(0); // terminate with ASCII zero
media_Flush();
media_SetAdd(0, 1024); // reset the media address
while(char:=media_ReadByte())
to(COM0); putch(char); // print the stored string to the COM port
wend
repeat forever
charwidth
charwidth is used to calculate the width in pixel units for a string, based on the currently selected font. The font can be proportional or monospaced. If the total width of the string exceeds 255 pixel units, the function will return the 'wrapped' (modulo 8) value.
Syntax: charwidth('char');
| Arguments | Description |
|---|---|
| char | The ascii character for the width calculation. |
Returns: The width of a single character in pixel units.
Example
// Example
str := "HELLO\nTHERE"; // note that this string spans 2 lines due to the \n.
width := strwidth(str); // get the width of the string, this will also capture the height.
height := strheight(); // note, invoking strwidth also calcs height which we can now read.
// The string above spans 2 lines, strheight(.) will calculate height correctly for multiple lines.
len := strlen(str); // the strlen() function returns the number of characters in a string.
print("\nLength=",len); // NB: the \n in "HELLO \nTHERE" is counted as a character.
txt_FontID(MS_SanSerif8x12); // select this font
w := charwidth('W'); // get a characters width
h := charheight('W'); // and height
txt_FontID(0); // back to default font
print ("\n'W' is " ,w, " pixels wide"); // show width of a character 'W' in pixel units.
print ("\n'W' is " ,h, " pixels high"); // show height of a character 'W' in pixel units.
charheight
charheight is used to calculate the height in pixel units for a string, based on the currently selected font. The font can be proportional or monospaced.
Syntax: charheight('char');
| Arguments | Description |
|---|---|
| char | The ascii character for the height calculation. |
Returns: The height of a single character in pixel units.
Example: See example in charwidth().
strwidth
strwidth returns the width of a zero terminated string in pixel units. Note that any string constants declared in your program are automatically terminated with a zero as an end marker by the compiler. Any string that you create in the DATA section or MEM section must have a zero added as a terminator for this function to work correctly.
Syntax: strwidth(pointer);
| Arguments | Description |
|---|---|
| pointer | The pointer to a zero (0x00) terminated string. 'pointer' may be a constant or pointer to word aligned variable. |
Returns: The width of a string in pixel units, can be multiline.
Example: See example in charwidth().
strheight
strheight returns the height of a zero terminated string in pixel units. The strwidth function must be called first which makes available width and height. Note that any string constants declared in your program are automatically terminated with a zero as an end marker by the compiler. Any string that you create in the DATA section or MEM section must have a zero added as a terminator for this function to work correctly.
Syntax: strheight();
Returns: The height of a string in pixel units, can be multiline.
Example: See example in charwidth().
strlen
strlen returns the length of a zero terminated string in character units. Note that any string constants declared in your program are automatically terminated with a zero as an end marker by the compiler. Any string that you create in the DATA section or MEM section must have a zero added as a terminator for this function to work correctly.
Syntax: strlen(pointer);
| Arguments | Description |
|---|---|
| pointer | The pointer to a zero (0x00) terminated string. |
Returns: The length of a string in character units.
Example: See example in charwidth().
txt_Set
Given a function number and a value, set the required text control parameter, such as size, colour, and other formatting controls. This function is extremely useful in a loop to select multiple parameters from a data statement or a control array. Note also that each function available for txt_Set has a single parameter 'shortcut' function that has the same effect.
| # | Predefined Name | Description | Value |
|---|---|---|---|
| 0 | TEXT_COLOUR | Set the text foreground colour. | Colour 0-65535 |
| 1 | TEXT_HIGHLIGHT | Set the text background colour. | Colour 0-65535 |
| 2 | FONT_ID | Set the required font. See font table Note: The value could be the name of a custom font included in a users program in a data statement. |
0 or FONT1 1 or FONT2 2 or FONT3 |
| 3 | TEXT_WIDTH | Set the text width multiplier. | 1 to 16 Default = 1 |
| 4 | TEXT_HEIGHT | Set the text height multiplier. | 1 to 16 Default = 1 |
| 5 | TEXT_XGAP | Set the pixel gap between characters. The gap is in pixel units. | 0 to 32 Default = 0 |
| 6 | TEXT_YGAP | Set the pixel gap between lines. The gap is in pixel units. | 0 to 32 Default = 0 |
| 7 | TEXT_PRINTDELAY | Set the delay between character printing to give a 'teletype' like effect. | Default = 0 msec |
| 8 | TEXT_OPACITY | Selects whether or not the 'background' pixels are drawn. | 0 or TRANSPARENT 1 or OPAQUE Default = 1 (OPAQUE) |
| 9 | TEXT_BOLD | Embolden text | 0 or 1 (OFF or ON ) |
| 10 | TEXT_ITALIC | Italicise text | 0 or 1 (OFF or ON ) |
| 11 | TEXT_INVERSE | Inverted text | 0 or 1 (OFF or ON ) |
| 12 | TEXT_UNDERLINED | Underlined text | 0 or 1 (OFF or ON ) |
| 13 | TEXT_ATTRIBUTES | Control of functions 9,10,11,12 grouped (bits can be combined by using logical 'or' of bits) nb:- bits 0-3 and 8-15 are reserved | 16 or BOLD 32 or ITALIC 64 or INVERSE 128 or UNDERLINED |
| 14 | TEXT_WRAP | Sets the pixel position where text wrap will occur at RHS The feature automatically resets when screen mode is changed. The value is in pixel units. Default value is 0. | 0 to n (OFF or Value) |
Single parameter short-cuts for txt_Set() functions.
| Function Syntax | Function Action | Value |
|---|---|---|
| txt_FGcolour(colour) | Set the text foreground colour. | Colour 0 - 65535 |
| txt_BGcolour(colour) | Set the text background colour. | Colour 0 - 65535 |
txt_FontID |
Set the required font. See Font table. Note: The value could also be the name of a custom font included in a users program in a data statement, or the handle returned from file_LoadImageControl() for a uSD based font. |
0 to 2 or FONT1 FONT2 FONT3 |
| txt_Width(multiplier) | Set the text width multiplier. | 1 to 16 Default = 1 |
| txt_Height(multiplier) | Set the text height multiplier. | 1 to 16 Default = 1 |
| txt_Xgap(pixelcount) | Set the pixel gap between characters. The gap is in pixel units. | 0 to 32 Default = 0 |
| txt_Ygap(pixelcount) | Set the pixel gap between lines. The gap is in pixel units. | 0 to 32 Default = 0 |
| txt_Delay(millisecs) | Set the delay between character printing to give a 'teletype' like effect. | (not used) |
| txt_Opacity(mode) | Selects whether or not the 'background' pixels are drawn | 0 or TRANSPARENT 1 or OPAQUE Default = 0 |
| txt_Bold(mode) | Embolden text | 0 or 1 (OFF or ON) |
| txt_Italic(mode) | Italic text | 0 or 1 (OFF or ON) |
| txt_Inverse(mode) | Inverted text | 0 or 1 (OFF or ON) |
| txt_Underlined | Underlined text | 0 or 1 (OFF or ON) |
| txt_Attributes(value) | Control of functions 9, 10, 11, 12 grouped (bits can be combined by using logical 'OR' of bits) nb:- bits 0-3 and 8-15 are reserved | 16 or BOLD 32 or ITALIC 64 or INVERSE 128 or UNDERLINED |
| txt_Wrap | Sets the pixel position where text wrap will occur at RHS The feature automatically resets when screen mode is changed. The value is in pixel units. Default value is 0. | 0 to n(OFF or Value) |
Font Table
| Font ID | Value |
|---|---|
| System font | 0 or FONT_1 |
| Default fonts | 2 or FONT_3 |
Syntax: txt_Set(function, value);
| Arguments | Description |
|---|---|
| functions | The function number determines the required action for various text control functions. Usually a constant, but can be a variable, array element, or expression. There are pre-defined constants for each of the functions. |
| value | A variable, array element, expression or constant holding a value for the selected function. |
Returns: None
Example: TODO
Timer Functions
sys_T
Returns the current value of the rolling 32bit system timer (1mse) LO word.
Syntax: sys_T();
Returns: The value of system timer. (LO Word)
Example
sys_T_HI
Returns the current value of the rolling 32bit system timer (1mse) HI word.
Syntax: sys_T_HI();
Returns: The value of system timer. (HI Word)
Example
sys_SetTimer
Set a countdown on the selected timer or 'top-up' if required. There are 8 timers TIMER0 to TIMER7 which stop at the count of 0. Maximum timeout period is 65535 milliseconds or 65.535 seconds.
A timer can be read with the sys_GetTimer("timernum") function.
Syntax: sys_SetTimer(timernum, value);
| Arguments | Description |
|---|---|
| timernum | One of eight timers TIMER0 to TIMER7. |
| value | Countdown period in milliseconds. |
Returns: None
Example
sys_GetTimer
Returns 0 if timer has expired, or the current countdown value. There are 8 timers TIMER0 to TIMER7 which stop at the count of 0. Maximum timeout period is 65535 milliseconds or 65.535 seconds.
A timer can be set with the sys_SetTimer("timernum", "value") function.
Syntax: sys_GetTimer(timernum);
| Arguments | Description |
|---|---|
| timernum | One of eight timers TIMER0 to TIMER7. |
Returns: 0 if timer has expired, or the current countdown value.
Example
sys_SetTimerEvent
Set a function to be called for selected timer. When the timer reaches zero, the function is called. The called function must not have any parameters, and should not have a return value. This is necessary because the timer event is invoked asynchronously to the mainline program (i.e, it is not called in the normal way, so parameters and return values don’t apply).
sys_SetTimerEvent(timernum, 0) disables the timer event.
Note
When a child process is run using the file_run or file_exec function, or if a file was loaded with file_Loadfunction and is executed, the loaded process gets its own code and memory space, therefore, any timer that reaches zero that has a timer event attached in the parent code space, will fail and cause a crash as an attempt is made to force the program counter to some wild place in the child process - There are 2 ways to overcome this problem.
- If a child process will not be requiring the use of any timers or timer events, the parent program can simply use the eventsPostpone() function before calling or entering the child process. Once the parent program regains control, the eventsResume() function will allow any events in the queue to then be processed. The side effect of this method is that several events may bank up, and will execute immediately once the eventsResume() takes place. This however disallows a child process to use any timer events in the sub program so method 2 is preferable in this case.
- The parent program can 'disconnect' the event(s) by setting it/them to zero prior to child process execution, or setting the associated timer to zero so the event wont fire. In either case, it is necessary to do the following:
while(sys_EventQueue());
to ensure the event queue is empty prior to calling the child process. Note also that if just the timer is set to zero, the child process cannot use this timer. If the timer was now set to a value and the old event still existed, when the timer reaches zero the 'bad' parent address event will fire causing a crash.
The reverse situation also applies of course, the same level of respect is required if a child program needs to use any timer events. Method [1] (above) will not work as the events have been postponed, stopping the child process from using any timer events. If the child process did an eventsResume() in this case, everything would crash miserably. So the same applies, a child that uses any timer events must respect any timers that may be used by the parent, and a child must zero the sys_SetTimerEvent before returning to the parent.
Syntax: sys_SetTimerEvent(timernum, function);
| Arguments | Description |
|---|---|
| timernum | One of eight timers TIMER0 to TIMER7. |
| function | Event Function to be queued. |
Returns: Any previous event function address, or zero if there was no previous function.
Example
sys_EventQueue
Returns the max number of events that were pending in the event queue since the last call to this function. This can be used to assess event overhead burden, especially after or during a sys_EventsPostpone action.
Syntax: sys_EventQueue();
Returns: Number of events.
Example
sys_EventsPostpone
Postpone any events until the sys_EventResume function is executed. The event queue will continue to queue events, but no action will take place until a sys_EventResume function is encountered. The queue will continue to receive up to 32 events before discarding any further events. This function is required to allow a sequence of instructions or functions to occur that would otherwise be corrupted by an event occurring during the sequence of instructions or functions. A good example of this is when you set a position to print, if there was no way of locking the current sequence, an event may occur which does a similar thing, and a contention would occur - printing to the wrong position. This function should be used wisely, if any action that is required would take considerable time, it is better to disable any conflicting event functions with a bypass flag, then restart the conflicting event by re-issuing a timer value.
Syntax: sys_EventsPostpone();
Returns: None
Example
sys_EventsResume
Resume any postponed events. The queue will try to execute any events that were incurred during the postponed period. Note that queued events are only checked for and executed at the end of each 4DGL instruction.
Syntax: sys_EventsResume();
Returns: None
Example
sys_DeepSleep
Deep Sleep is a sleep state that is ‘deeper’ than the regular Sleep (for most display modules) and therefore consumes less power. Some displays do not support being powered to a lower state, so sleep and deepsleep power consumption can sometimes be roughly the same.
Puts the display and processor into the lowest power mode for a period of time. If "units" is zero, the display goes into sleep mode forever and needs power cycling to re-initialize. If "units" is 1 to 65535, the display will sleep for that period of time, or will be woken when touch screen is touched. The function returns the count of "units" that are remaining when the screen was touched. When returning from deep sleep mode, some displays might lose their screen and/or need to be reinitialised with disp_Init().
New in v0.7 PmmC.
Syntax: sys_DeepSleep(units);
| Arguments | Description |
|---|---|
| units | Sleep timer units are approx 1 second. When in sleep mode, timing is controlled by an RC oscillator, therefore, timing is not totally accurate and should not be relied on for timing purposes. |
Returns: Remaining time units when touch screen is touched, else returns zero.
Example
sys_Sleep
Regular sleep, which puts the display and processor into low power mode for a period of time. If "units" is zero, the display goes into sleep mode forever and needs power cycling to re-initialize. If "units" is 1 to 65535, the display will sleep for that period of time, or will be woken when touch screen is touched. The function returns the count of "units" that are remaining when the screen was touched. When returning from sleep mode, the display and processor are restored from low power mode.
Note
sys_Sleep() was found to have an issue in PmmC’s prior to R33, the units value was not always near 1 second. This has been corrected in PmmC R33.
Syntax: sys_Sleep(units);
| Arguments | Description |
|---|---|
| units | Sleep timer units are approx 1 second. When in sleep mode, timing is controlled by an RC oscillator, therefore, timing is not totally accurate and should not be relied on for timing purposes. |
Returns: Remaining time units when touch screen is touched, else returns zero.
Example
iterator
Sets the iterator size for the next postinc, postdec, preinc or predec by a specified value. The offset will return to 1 after the next operation.
Syntax: iterator_(offset);
| Arguments | Description |
|---|---|
| offset | Offset size for the next ++ or - - command. |
Returns: None
Example
Touch Screen Functions
touch_DetectRegion
Specifies a new touch detect region on the screen. This setting will filter out any touch activity outside the region and only touch activity within that region will be reported by the status poll touch_Get(0) function.
Syntax: touch_DetectRegion(x1, y1, x2, y2);
| Arguments | Description |
|---|---|
| x1 | specifies the horizontal position of the top left corner of the region. |
| y1 | specifies the vertical position of the top left corner of the region. |
| x2 | specifies the horizontal position of the bottom right corner of the region. |
| y2 | specifies the vertical position of the bottom right corner of the region. |
Returns: None
Example
gfx_Rectangle(100, 100, 201, 201, YELLOW); // draw a rectangle with a yellow border
touch_DetectRegion(101, 101, 200, 200); // limit touch detect region towithin the rectangle
touch_Set
Sets various Touch Screen related parameters.
mode = 0: Enable Touch Screen.
touch_Set(0); - Enables and initialises Touch Screen hardware.
mode = 1: Disable Touch Screen.
touch_Set(1); - Disables the Touch Screen.
mode = 2: Default Touch Region.
touch_Set(2); - This will reset the current active region to default which is the full screen area
Note
Touch Screen task runs in the background and disabling it when not in use will free up extra resources for 4DGL CPU cycles.
Syntax: touch_Set(mode);
| Arguments | Description |
|---|---|
| mode | mode = 0 mode = 1 mode = 2 |
Returns: None
Example
touch_Get
Returns various Touch Screen parameters to caller.
mode = 0 - Returns the various states of the touch screen
- 0 = INVALID/NOTOUCH
- 1 = PRESS
- 2 = RELEASE
- 3 = MOVING
mode = 1 - Returns the X coordinates of the touch reported by mode 0
mode = 2 - Returns the Y coordinates of the touch reported by mode 0
Syntax: touch_Get(mode);
| Arguments | Description |
|---|---|
| mode | mode = 0: Get Status mode = 1: Get X coordinates mode = 2: Get Y coordinates |
Returns: The various Touch Screen parameters to caller.
Example
state := touch_Get(TOUCH_STATUS); // get touchscreen status
x := touch_Get(TOUCH_GETX);
y := touch_Get(TOUCH_GETY);
if (state == TOUCH_PRESSED) // see if Exit hit
if ( x > 170 && y > 280 ) // EXIT button
gfx_Cls();
exit := 1;
endif
if (vertical)
if ( x > 170 && (y > 240 && y < 270 )) // Horizontal button
vertical := 0;
exit := 1;
endif
else
if ( x > 170 && (y > 200 && y < 230 )) // Vertical button
vertical := 1;
exit := 2;
endif
endif
endif
System Registers Memory
The following tables outline in detail the PICASO system registers and flags.
| Label | Address DEC |
Address HEX |
Usage |
|---|---|---|---|
| RANDOM_LO | 32 | 0x20 | random number generator LO word |
| RANDOM_HI | 33 | 0x21 | random number generator HI word |
| SYSTEM_TIMER_LO | 34 | 0x22 | 1msec system timer LO word |
| SYSTEM_TIMER_HI | 35 | 0x23 | 1msec system timer HI word |
| TIMER0 | 36 | 0x24 | 1msec user timer 0 |
| TIMER1 | 37 | 0x25 | 1msec user timer 1 |
| TIMER2 | 38 | 0x26 | 1msec user timer 2 |
| TIMER3 | 39 | 0x27 | 1msec user timer 3 |
| TIMER4 | 40 | 0x28 | 1msec user timer 4 |
| TIMER5 | 41 | 0x29 | 1msec user timer 5 |
| TIMER6 | 42 | 0x2A | 1msec user timer 6 |
| TIMER7 | 43 | 0x2B | 1msec user timer 7 |
| SYS_X_MAX | 44 | 0x2C | display hardware X res-1 |
| SYS_Y_MAX | 45 | 0x2D | display hardware Y res-1 |
| GFX_XMAX | 46 | 0x2E | width of current orientation |
| GFX_YMAX | 47 | 0x2F | height of current orientation |
| GFX_LEFT | 48 | 0x30 | image left real point |
| GFX_TOP | 49 | 0x31 | image top real point |
| GFX_RIGHT | 50 | 0x32 | image right real point |
| GFX_BOTTOM | 51 | 0x33 | image bottom real point |
| GFX_X1 | 52 | 0x34 | image left clipped point |
| GFX_Y1 | 53 | 0x35 | image top clipped point |
| GFX_X2 | 54 | 0x36 | image right clipped point |
| GFX_Y2 | 55 | 0x37 | image bottom clipped point |
| GFX_X_ORG | 56 | 0x38 | current X origin |
| GFX_Y_ORG | 57 | 0x39 | current Y origin |
| GFX_HILITE_LINE | 58 | 0x3A | current multi line button hilite line |
| GFX_LINE_COUNT | 59 | 0x3B | count of lines in multiline button |
| GFX_LAST_SELECTION | 60 | 0x3C | Last selected line |
| GFX_HILIGHT_BACKGROUND | 61 | 0x3D | multi button hilite background colour |
| GFX_HILIGHT_FOREGROUND | 62 | 0x3E | multi button hilite foreground colour |
| GFX_BUTTON_FOREGROUND | 63 | 0x3F | store default text colour for hilite line tracker |
| GFX_BUTTON_BACKGROUND | 64 | 0x40 | store default button colour for hilite line tracker |
| GFX_BUTTON_MODE | 65 | 0x41 | store current buttons mode |
| GFX_TOOLBAR_HEIGHT | 66 | 0x42 | height above |
| GFX_STATUSBAR_HEIGHT | 67 | 0x43 | height below |
| GFX_LEFT_GUTTER_WIDTH | 68 | 0x44 | width to left |
| GFX_RIGHT_GUTTER_WIDTH | 69 | 0x45 | width to right |
| GFX_PIXEL_SHIFT | 70 | 0x46 | pixel shift for button depress illusion |
| GFX_VECT_X1 | 71 | 0x47 | gp rect, used by multiline button to hilite required line |
| GFX_VECT_Y1 | 72 | 0x48 | |
| GFX_VECT_X2 | 73 | 0x49 | |
| GFX_VECT_Y2 | 74 | 0x4A | |
| GFX_THUMB_PERCENT | 75 | 0x4B | size of slider thumb as percentage |
| GFX_THUMB_BORDER_DARK | 76 | 0x4C | darker shadow of thumb |
| GFX_THUMB_BORDER_LIGHT | 77 | 0x4D | lighter shadow of thumb |
| TOUCH_XMINCAL | 78 | 0x4E | touch calibration value |
| TOUCH_YMINCAL | 79 | 0x4F | touch calibration value |
| TOUCH_XMAXCAL | 80 | 0x50 | touch calibration value |
| TOUCH_YMAXCAL | 81 | 0x51 | touch calibration value |
| IMG_WIDTH | 82 | 0x52 | width of currently loaded image |
| IMG_HEIGHT | 83 | 0x53 | height of currently loaded image |
| IMG_FRAME_DELAY | 84 | 0x54 | if image else inter frame delay for movie |
| IMG_FLAGS | 85 | 0x55 | bit 4 determines colour mode other bits reserved |
| IMG_FRAME_COUNT | 86 | 0x56 | count of frames in a movie |
| IMG_PIXEL_COUNT_LO | 87 | 0x57 | count of pixels in the current frame |
| IMG_PIXEL_COUNT_HI | 88 | 0x58 | count of pixels in the current frame |
| IMG_CURRENT_FRAME | 89 | 0x59 | last frame shown |
| MEDIA_ADDRESS_LO | 90 | 0x5A | uSD byte address LO |
| MEDIA_ADDRESS_HI | 91 | 0x5B | uSD byte address HI |
| MEDIA_SECTOR_LO | 92 | 0x5C | uSD sector address LO |
| MEDIA_SECTOR_HI | 93 | 0x5D | uSD sector address HI |
| MEDIA_SECTOR_COUNT | 94 | 0x5E | uSD number of bytes remaining in sector |
| TEXT_XPOS | 95 | 0x5F | text current x pixel position |
| TEXT_YPOS | 96 | 0x60 | text current y pixel position |
| TEXT_MARGIN | 97 | 0x61 | text left pixel pos for carriage return |
| TXT_FONT_TYPE | 98 | 0x62 | font type, 0 = system font, else pointer to user font |
| TXT_FONT_MAX | 99 | 0x63 | max number of chars in font |
| TXT_FONT_OFFSET | 100 | 0x64 | starting offset (normally 0x20) |
| TXT_FONT_WIDTH | 101 | 0x65 | current font width |
| TXT_FONT_HEIGHT | 102 | 0x66 | current font height |
| GFX_TOUCH_REGION_X1 | 103 | 0x67 | touch capture region |
| GFX_TOUCH_REGION_Y1 | 104 | 0x68 | touch capture region |
| GFX_TOUCH_REGION_X2 | 105 | 0x69 | touch capture region |
| GFX_TOUCH_REGION_Y2 | 106 | 0x6A | touch capture region |
| GFX_CLIP_LEFT_VAL | 107 | 0x6B | left clipping point (set with gfx_ClipWindow(...) |
| GFX_CLIP_TOP_VAL | 108 | 0x6C | top clipping point (set with gfx_ClipWindow(...) |
| GFX_CLIP_RIGHT_VAL | 109 | 0x6D | right clipping point (set with gfx_ClipWindow(...) |
| GFX_CLIP_BOTTOM_VAL | 110 | 0x6E | bottom clipping point (set with gfx_ClipWindow(...) |
| GFX_CLIP_LEFT | 111 | 0x6F | current clip value (reads full size if clipping turned off) |
| GFX_CLIP_TOP | 112 | 0x70 | current clip value (reads full size if clipping turned off) |
| GFX_CLIP_RIGHT | 113 | 0x71 | current clip value (reads full size if clipping turned off) |
| GFX_CLIP_BOTTOM | 114 | 0x72 | current clip value (reads full size if clipping turned off) |
| GRAM_PIXEL_COUNT_LO | 115 | 0x73 | LO word of count of pixels in the set GRAM area |
| GRAM_PIXEL_COUNT_HI | 116 | 0x74 | HI word of count of pixels in the set GRAM area |
| TOUCH_RAW_X | 117 | 0x75 | 12 bit raw A2D X value from touch screen |
| TOUCH_RAW_Y | 118 | 0x76 | 12 bit raw A2D Y value from touch screen |
| GFX_LAST_CHAR_WIDTH | 119 | 0x77 | calculated char width from last call to charWidth function |
| GFX_LAST_CHAR_HEIGHT | 120 | 0x78 | calculated height from last call to charHeight function |
| GFX_LAST_STR_WIDTH | 121 | 0x79 | calculated width from last call to strWidth function |
| GFX_LAST_STR_HEIGHT | 122 | 0x7A | calculated height from last call to strHeight function |
Runtime Errors
| Error No. | Error Meaning | Category |
|---|---|---|
| 1 | Failed to receive 'L' during loading process from Workshop | Workshop |
| 2 | Did not receive valid header info from Workshop | Workshop |
| 3 | Header size does not match loader info | Workshop |
| 4 | Could not allocate enough memory for program | Workshop |
| 5 | Loader checksum error | Workshop |
| 6 | Did not receive header prior to 'L' command | Workshop |
| 7 | Header size entry does not match loader value | Workshop |
| 8 | Failed to load program from FLASH | Internal |
| 9 | Could not allocate code segment | File Loader |
| 10 | Could not load function file from disk | File Loader |
| 11 | Bad header in program file | File Loader |
| 12 | Header in program file differs from file size | File Loader |
| 13 | Could not allocate global memory for program file | File Loader |
| 14 | Program File checksum error | File Loader |
| 15 | EVE Stack Overflow | System |
| 16 | Unsupported PmmC function | V1: fnc V2: 1st Arg |
| 17 | Illegal COM0 Event Function address | V1: addr V2: (ignored) |
| 18 | Illegal COM1 Event Function address | V1: addr V2: (ignored) |
| 19 | Bad txt_Set(...) command number | V1: command V2: value |
| 20 | Bad gfx_Get(...) command number | V1: command V2: (ignored) |
| 21 | Bad gfx_Set(...) command number | V1: command V2: value |
| 22 | Bad address for peekW or pokeW | V1: command V2: (ignored) |
| 23 | Bad timer number for sys_SetTimer(..) or sys_GetTimer(..) | V1: tnum V2: value |
| 24 | Bad timer number for sys_SetTimerFunction(...) | V1: tnum V2: funcaddr |
Revision History
Document Revision
| Revision | Date | Description |
|---|---|---|
| 1.0 | 20/06/2010 | First Release |
| 2.0 | 25/10/2010 | 1 - Incorrect heading and discrepancy in the description of bus_Write Function; fixed. 2 - Fixed typing error in the bus_Read Function. 3 - Erroneous references in the txt_Set() function to “note #5”, “note #6”, “note #7” and “note #8” removed. Proper descriptions added. 4 - Replaced FONT_SIZE with FONT_ID at several places. 5 - X_RES is replaced with X_MAX. Y_RES is replaced with Y_MAX in the gfx_ClipWindow() function. 6 - str_Append is replaced with str_Cat in the example in the str_Cat() function. 7 - str_Append is replaced with str_CatN in the example in the str_CatN() function. |
| 3.0 | 17/11/2011 | 1 - Fixed typing error in the mem_Alloc(), mem_AllocV() and mem_Allocz() functions. 2 - Added Details for Transparency functions. See the gfx_Set() section. 3 - Added Details for uVGA-II/III related functions in the gfx_Set() section. 4 - Added the disp_Sync() function. disp_Sync(line) command added for uVGA-II/III module. 5 - Updated SPI modes and SPI speeds. Note SPI diagram in the spi_Init() function. 6 - Fixed typing error in the sys_T() and sys_T_HI() functions. It's a 32 bit Timer. 7 - Fixed typing error in the Description in the I2C_Open() function. |
| 4.0 | 17/02/2012 | 1 - Removed predefined numbers from the gfx_Set() table. gfx_Set() should only be used with predefined names. 2 - Transparency, Contrast and Multiple Page Display/Read/Write details updated in the gfx_Set() section. 3 - Fixed typo in the strheight() section. 4 - Added the CY() function. 5 - Added the umul_1616(&res32, val1, val2) function. 6 - Added the uadd_3232(&res32, &val1, &val2) function. 7 - Added the usub_3232(&res32, &val1, &val2) function. 8 - Added the ucmp_3232(&val1, &val2) function. 9 - Added the str_ByteMove(src, dest, count) function. 10 - Added the str_Copy(dest, src) function. 11 - Added the str_CopyN(dest, src, count) function. |
| 5.0 | 08/06/2012 | 1 - Fixed typing error in the SWAP command. See the SWAP() section. 2 - Fixed typing errors in the strheight()) section. 3 - Updated COM1 Default Baud rate details. 4 - Fixed typing error in the example under the sys_EventsPostpone() section. 5 - Added details to the gfx_Cls() command. 6 - com_TXbuffer() and com1_TXbuffer() functions have been modified and take an extra parameter. It applies to PmmC R29 or above. 7 - Description updated, Image control will now show error box for out of range video frames. If frame is set to -1, just a rectangle will be drawn in background colour to blank an image. It applies to PmmC R29 or above. See the img_SetWord() function. 8 - Description updated, Image control will now show error box for out of range video frames. Also, if frame is set to -1, just a rectangle will be drawn in background colour to blank an image. It applies to PmmC R29 or above. See the media_VideoFrame() function. |
| 6.0 | 12/09/2012 | Reformatted, minor document updates |
| 6.1 | 23/11/2012 | Fixed minor TOC numbering issue 1 - It is now possible for a parent to access child globals when using file_LoadFunction. See the updated file_LoadFunction() function. Example added. Applies to PmmC R31 and above. 2 - Added description to the sys_SetTimerEvent(timernum, function) section. 3 - Added the com_TXbufferHold(state) function. 4 - Fixed the "Returns" part of the com_TXcount() section. 5 - Updated description for the com_TXemptyEvent(...) section. com_TXemptyEvent(Function) is changed to com_TXemptyEvent(FunctionAddress). Added a better example in the com_TXemptyEvent(...) section. |
| 6.2 | 17/12/2012 | Fixed minor issues in the wording and return types of some functions File_ScreenCapture – Typo in x and y description Gfx_Origin – Incorrect description Mem_Free – Return was incorrect Gfx_Get – Some modes were not listed, these have been added File_Image – Return was incorrect Media_Flush – Return was incorrect Sys_Sleep – Note added File_Exists – Removed wildcard support description, this was not supported File_Run, File_Exec – Status should be Value, otherwise OK PutW, putC – Return was incorrect SetBaud – Some % Errors listed in the SetBaud table were incorrect - Updated |
| 6.3 | 12/01/2013 | Fixes to str_Length() example Fixes to typo in mem_AllocV name, and description of size type and return improved Fixes to mem_Alloc size type and return improved Addition to type of Size in mem_Set command, and addition on an example Fixes to sys_SetTimerEvent() example, fix of typo Improvements made to img_SetWord and img_GetWord constant listings Improvement of img_SetImageControl description |
| 6.4 | 01/02/2013 | Removed str_String from listing as it didn’t exist Updated the Display I/O Functions section. |
| 6.5 | 04/02/2013 | SCREEN_MODE constants fixed, incorrectly documented |
| 6.6 | 07/02/2013 | Addition content added to sys_SetTimerEvent description |
| 6.7 | 13/02/2013 | Corrections to Contrast values for EXCEPTIONS sections |
| 6.8 | 17/02/2013 | Touch Get explanation of Mode 1 and Mode 2 extended |
| 6.9 | 02/04/2013 | Updated I2C_Write returns |
| 6.10 | 30/04/2013 | Updated setbaud and com_SetBaud information |
| 6.11 | 11/05/2013 | Detaill added to descriptions of serout() and com_TXbuffer() functions |
| 6.12 | 30/05/2013 | gfx_Selection() function removed due to instability some time ago from the PmmC, however was left in this document in error |
| 6.13 | 12/06/2013 | Updated file_error() table, updated sentence in the [print()][#print] section, and updated comment in the sys_SetTimer() section. |
| 6.14 | 05/07/2013 | Added detail to file_Write and file_Read functions regarding their pointers, removed incorrect information about uVGAII/III orientation, and gfx_TriangleFilled functions |
| 6.15 | 03/09/2013 | Added missing disp_Init() function, and reworded the img_Touched() description |
| 6.16 | 22/10/2013 | Added new Functions disp_Disconnect() and sys_DeepSleep(). Fix spelling mistake in file_LoadImageControl |
| 6.17 | 18/12/2013 | Fixed error return codes in file_PlayWAV and added missing code. Removed uLCD-43PT option for SCREEN_RES |
| 6.18 | 21/03/2014 | Documented v4.0 PmmC’s changes to files opened in append mode. |
| 6.19 | 22/12/2014 | Added information for file_LoadImageControl Mode 2. Updated control block size in file_Mount. Added information about source of uSD based font in txt_FontID. Added note about restriction of turning clipping on and off. Added information about the use of TRANSPARENCY. Clarified information about events. |
| 6.20 | 14/07/2015 | Added notes to comx_TXbufferHold. Improved return description for str_Match and str_MatchI. Added str_Printf to ‘to’ function. Updated example for str_Cat, str_CatN, str_Find, str_FindI, str_Match, str_MatchI and file_Exec. |
| 6.21 | 19/08/2016 | Added I_TOUCH_DISABLE to img_SetAttributes and img_ClearAttributes. |
| 7.0 | 01/05/2017 | Updated formatting and contents |
| 7.1 | 21/03/2019 | Updated formatting |
| 7.2 | 08/12/2020 | Updated incorrect return information for mem_Realloc function, and its syntax |
| 7.3 | 21/12/2020 | Added baud rate formula for calculating actual baud rate and error %. See setbaud() and com_SetBaud() functions. |
| 8.0 | 03/11/2023 | Modified manual for web-based documentation |