# glcd_common

glcd_common - generic routines for graphic lcd

Author | Stef Mientki, Serkan Ayyldz Copyright © 2006..2022, all rights reserved.
Adapted-by | Joep Suijs, Matthew Schinkel, Rob Hamerling, Rob Jansen
Compiler | 2.5r6

Description

    Generic routines for graphic lcds
    glcd_line
    glcd_box
    glcd_box_fill
    glcd_ellipse
    glcd_circle
    glcd_draw_image
    .
    Defines a common API, a common interface, where several parameters and
    procedures remain device specific and should be implemented in device library.
    Once interface is implemented, many features come for "free".
    This common API is defined in glcd_common.jal and glcd_font.jal
    .
    In order to honor this common interface, and benefit its features,
    the following must be implemented in the device specific library.
      * GLCD_X_PIXELS: (const) specifies display's width in pixels
      * glcd_display_y_size: (const) specifies display's height in pixels
      * GLCD_COLOR_BITS: (const) specifies the number of bits required
        for colors (1 for black & white), (16 for 16 bit color)
      * glcd_pen_color: (var|const) specifies color of the pen
      * glcd_background_color: (var|const) specifies the background color
      * glcd_write_char(x,y,char): (proc) draw "char" at position (x,y). If no
        glcd_write_char is defined in the device specific library, pixel by
        pixel method will be used by default for glcd_font.jal.
      * glcd_write_pixel(x,y): (proc) assuming pen and background color
        previously set, draw a pixel at position (x,y) using defined colors.
        This is the main procedure used by pixel-related features, like drawing
        a line, circle, etc... In some cases, where glcd_write_char() can't be
        used glcd_write_pixel() can also be used to draw chars. If not
        implemented pixel-related features won't be available.
    .
    The device library or user program may also specify:
      * GLCD_CLIPPING: (const) specifies if clipping is desired.
                       TRUE means that pixels of an ellipse beyond display
                       boundaries will not be sent to the display
                       (thus not shown on the wrong places).
                       When not declared, or set FALSE, no clipping is
                       performed and pixels may be written at unexpected
                       places.

Notes

      Changes by Rob Hamerling (Nov/Dec 2011):
      - fixed typo in comments above (GLCD_Y_SIZE -> glcd_display_y_size)
      - corrected irrelevant comments (artifacts of older versions)
      - changed sword to sbyte*3 of local variables in glcd_ellipse procedure
        to prevent overflow of intermediate results.
      - added [optional] clipping of pixels (of ellipse) when attempting
        to draw beyond display boundaries
      - fixed glcd_box_fill() for situation y1 < y0
      - minor code optimizations (incl some add/remove pragma inline)
      - comments: extended, corrected, aligned

Dependencies

- glcd_font

## Summary

### Global variables/contants

- `const GLCD_PEN_COLOR = 1`
- `const byte GLCD_BACKGROUND_COLOR = 0`
- `const GLCD_CLIPPING = FALSE`
- `const GLCD_X_SIZE = 1`
- `var byte*GLCD_X_SIZE glcd_char_x_pos = 0`
- `var byte*GLCD_Y_SIZE glcd_char_y_pos = 0`
- `var byte*GLCD_Y_SIZE glcd_display_y_size = GLCD_Y_PIXELS`
- `const GLCD_USE_BLOCK_WRITE = FALSE`
- `var byte*GLCD_X_SIZE glcd_display_x_size = GLCD_X_PIXELS`
- `const GLCD_Y_SIZE = 1`
- `const GLCD_COLOR_SIZE = 1`

### Procedures

- `glcd_write_char_pbp(byte*GLCD_X_SIZE in x, byte*GLCD_Y_SIZE in y, byte in value)`
- `glcd'put(byte in char)`
- `glcd_clear_screen()`
- `glcd_char_goto(byte in x, byte in y)`
- `glcd_write_char_block(byte*GLCD_X_SIZE in x, byte*GLCD_Y_SIZE in y, byte in value)`
- `glcd_circle(byte*GLCD_X_SIZE in cx, byte*GLCD_Y_SIZE in cy, byte in radius)`

### Functions

## API details

### Global variables/contants

- `const GLCD_PEN_COLOR = 1`

      Foreground (pen) color setting

- `const byte GLCD_BACKGROUND_COLOR = 0`

      Background color setting

- `const GLCD_CLIPPING = FALSE`

      Clipping requested (TRUE) or not (FALSE)

- `const GLCD_X_SIZE = 1`

      Width of the variables for x-coordinates

- `var byte*GLCD_X_SIZE glcd_char_x_pos = 0`

      Global variables for text processing

- `var byte*GLCD_Y_SIZE glcd_char_y_pos = 0`

  No documentation found

- `var byte*GLCD_Y_SIZE glcd_display_y_size = GLCD_Y_PIXELS`

  No documentation found

- `const GLCD_USE_BLOCK_WRITE = FALSE`

      Block writing capability of the glcd device specific library

- `var byte*GLCD_X_SIZE glcd_display_x_size = GLCD_X_PIXELS`

      We need to store the screen size due to the option of screen rotation by
      which the x size and y size can change.

- `const GLCD_Y_SIZE = 1`

      Width of the variables for y-coordinates (byte for max 256 pixels vertically)

- `const GLCD_COLOR_SIZE = 1`

      Number of colors of the specific glcd device

### Procedures

- `glcd_write_char_pbp(byte*GLCD_X_SIZE in x, byte*GLCD_Y_SIZE in y, byte in value)`

      Purpose:   Draw one character pixel by pixel - slowest method.
      Arguments: - x- and y-coordinates of character (upper left corner, in pixels)
       character to be displayed
      Notes:     Requires this procedure to be defined within your glcd library
      glcd_write_pixel() - draw one pixel to glcd

- `glcd'put(byte in char)`

      Pseudo variable 'glcd' for writing characters.

- `glcd_clear_screen()`

      Purpose:   Clear screen and character position to the upper left corner (0,0)
      Arguments: none
      Notes:     When block writes are not supported by your glcd, it is highly
      recommended that you define a custom glcd_clear_screen()
      procedure within your glcd's library otherwise this procedure will
      clear the screen pixel by pixel which is very slow.
      .
      Here's a list of procedures required in your glcd device library:
      glcd_block_address()      set start x,y and end x,y address
      glcd_block_write_color()  write data to each pixel in order
      Also must define this constant in your glcd device library and
      set your most efficient font type.
      const GLCD_BLOCK_WRITE_TYPE = FONT_TOP_LEFT_HORIZONTAL

- `glcd_char_goto(byte in x, byte in y)`

      Purpose:   Set location of next character to write
      Arguments: x- and y-coordinates in pixels of next character to read or write

- `glcd_write_char_block(byte*GLCD_X_SIZE in x, byte*GLCD_Y_SIZE in y, byte in value)`

      Purpose:   Draw one character with block write - efficient font printing.
      Arguments: - x- and y-coordinates of the character (upper left corner, in pixels)
       character to display
      Notes:     Only FONT_TOP_LEFT_HORIZONTAL is supported so far.
      Here's a list of procedures reqired in your glcd device library:
      glcd_block_address() - set start x,y and end x,y address
      glcd_block_write_color() - write data to each pixel in order
      Also must define this constant in your glcd device library and
      set your most efficient font type.
      const GLCD_BLOCK_WRITE_TYPE = FONT_TOP_LEFT_HORIZONTAL

- `glcd_circle(byte*GLCD_X_SIZE in cx, byte*GLCD_Y_SIZE in cy, byte in radius)`

      Purpose:    Draw a circle
      arguments:  - x- and -y-coordinates of the center of the circle
       radius radius of the circle
      Notes:      Using current pixel color
      The circle code may not give a round circle on the glcd.
      Author:     Paul D'haene

### Functions

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_glcd_nokia_5110_image.jal
16f877a | 16f877a_glcd_ks0108.jal
16f877a | 16f877a_glcd_t6963.jal
18f2580 | 18f2580_rtc_ds1302_glcd.jal
18f4550 | 18f4550_glcd_nokia_5110_image.jal
18f4550 | 18f4550_glcd_nokia_5110_gfx.jal
18f4550 | 18f4550_glcd_nokia_5110_pixel.jal
18f4550 | 18f4550_glcd_nokia_5110_sprite.jal
18f4550 | 18f4550_glcd_nokia_5110_font.jal
18f6310 | 18f6310_glcd_ks0108_math.jal