ws0010_set_character :: Quanser C Functions

navigation bar

ws0010_set_character

Defines a custom character for the Surenoo WS0010 OLED display.

Description

The ws0010_set_character function defines a custom character for the Surenoo WS0010 OLED display. Up to eight custom character glyphs may be defined, corresponding to the characters '\020' through '\027' or 0x10 to 0x17. Using these characters will produce the bitmap defined in the pattern for that character.

The pattern defines each line of the character being defined, with the five least-significant bits in each t_uint8 defining the pixels of that line. For example, to define the letter T, the pattern would be:

    pattern[0]  = 0b00011111 (0x1F)
    pattern[1]  = 0b00000100 (0x04)
    pattern[2]  = 0b00000100 (0x04)
    pattern[3]  = 0b00000100 (0x04)
    pattern[4]  = 0b00000100 (0x04)
    pattern[5]  = 0b00000100 (0x04)
    pattern[6]  = 0b00000100 (0x04)
    pattern[7]  = 0b00000000 (0x00) <= should generally be zero to allow for cursor

Note that only the five least-significant bits are used. Bit 0 is the rightmost pixel and bit 4 is the leftmost pixel. The baseline is in pattern[6]. The top of a typical character is in pattern[0].

Prototype

t_error
ws0010_set_character(t_ws0010 display, t_int code, const t_uint8 pattern[8]);

Parameters

t_ws0010 display

A handle to the display returned by the ws0010_open function.

t_int code

The character whose glyph is being defined. The character code must lie between '\020' and '\027' inclusive. Calling this function twice using the same character code will overwrite the previous glyph.

t_uint8 pattern[8]

The glyph pattern for the character. Each element of the array defines one pixel row of the character. The least-significant bit in each element represents the rightmost pixel and bit 4 represents the leftmost pixel. The top of the character is typically in pattern[0]. The baseline for the character should be in pattern[6].

Return value

The return value is zero if the operation is successful. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_DISPLAY_NOT_IN_TEXT_MODE

The display was opened in graphics mode so the text functions cannot be used.

Requirements

Include Files	Libraries
quanser_lcd_display.h	quanser_devices.lib;quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_ws0010 display;
t_error result = 
    ws0010_open("lcd://qbot_platform:1", &display);
if (result == 0) {
    static const t_uint8 pattern[8] =
    {
        0x1F, /* 0b00011111 */
        0x04, /* 0b00000100 */
        0x04, /* 0b00000100 */
        0x00, /* 0b00000000 */
        0x00, /* 0b00000000 */
        0x04, /* 0b00000100 */
        0x04, /* 0b00000100 */
        0x00  /* 0b00000000 */
    };
    const char message[] = "Here it is: \020!";
    ws0010_set_character(display, '\020', pattern);
    ws0010_print(display, 0, 0, message, ARRAY_LENGTH(message));
    ...
    ws0010_close(display);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open OLED display. %s (error %d)\n"), message, -result);
}