display.lcd.ili9341.spin

{
---------------------------------------------------------------------------------------------------
    Filename:       display.lcd.ili9341.spin
    Description:    Driver for ILI9341 LCD controllers
    Author:         Jesse Burt
    Started:        Oct 14, 2021
    Updated:        Feb 13, 2024
    Copyright (c) 2024 - See end of file for terms of use.
---------------------------------------------------------------------------------------------------
}

' memory usage for a buffered display would vastly exceed what's available
'   on the P1, so hardcode direct-to-display directive:
#define GFX_DIRECT
#include "graphics.common.spinh"


CON

    { /// default I/O settings - can be overridden in the parent object }
    WIDTH       = 320
    HEIGHT      = 240
    DBASEPIN    = 0
    RST         = 8
    CS          = 9
    DC          = 10
    WRX         = 11
    RDX         = 12
    { /// }


    BPP         = 16
    MAX_COLOR   = (1 << BPP)-1
    BYTESPERPX  = 1 #> BPP/8
    BPPDIV      = 1 #> (8 / BPP)
    BUFF_SZ     = (WIDTH * HEIGHT) / BPPDIV
    XMAX        = WIDTH-1
    YMAX        = HEIGHT-1
    CENTERX     = WIDTH/2
    CENTERY     = HEIGHT/2


' Display visibility modes
    ALL_OFF     = 0
    OFF         = 0
    NORMAL      = 1
    ON          = 1
    INVERTED    = 2
    ALL_ON      = 3

' Subpixel order
    RGB         = 0
    BGR         = 1

' Display refresh direction
    NORM        = 0
    INV         = 1

' Internal use
    VMH         = 0
    VML         = 1

    FCLK_DIV    = 0                         ' FRMCTR1
    FRM_RT      = 1

OBJ

    time: "time"                                ' timekeeping methods
    core: "core.con.ili9341"                    ' HW-specific constants
    com : "com.parallel-8bit"                   ' 8-bit Parallel I/O engine

VAR

    byte _RESET

    ' shadow registers
    word _vcomh, _vcoml
    byte _madctl, _pwr_ctrl2, _vmctrl1[2], _vcomoffs, _colmod, _frmctr1[2]
    byte _g3ctrl

PUB start(): status
' Start the driver using default I/O settings
    return startx(DBASEPIN, RST, CS, DC, WRX, WIDTH, HEIGHT)

PUB startx(DATA_BASEPIN, RES_PIN, CS_PIN, DC_PIN, WR_PIN, DISP_W, DISP_H): status
' Start driver using custom I/O settings
'   DATA_BASEPIN: first (lowest) pin of 8 data pin block (must be contiguous)
'   RES_PIN: display's hardware reset pin (optional, -1 to ignore)
'   CS_PIN: Chip Select
'   DC_PIN: Data/Command (sometimes labeled RS, or Register Select)
'   WR_PIN: Write clock
'   WIDTH, HEIGHT: display dimensions, in pixels
    if (    lookdown(DATA_BASEPIN: 0..24) and lookdown(CS_PIN: 0..31) and ...
            lookdown(DC_PIN: 0..31) and lookdown(WR_PIN: 0..31) )
        if ( status := com.init(DATA_BASEPIN, CS_PIN, DC_PIN, WR_PIN) )
            _RESET := RES_PIN
            set_dims(DISP_W, DISP_H)
            return
    ' if this point is reached, something above failed
    ' Double check I/O pin assignments, connections, power
    ' Lastly - make sure you have at least one free core/cog
    return FALSE

PUB defaults()
' Preset settings: defaults
    reset()
    time.msleep(5)

    visibility(OFF)
    gvdd_voltage(4_750)
    vgh_step_factor(7)
    vgl_step_factor(3)
    vcomh_voltage(5_000)
    vcoml_voltage(-0_600)
    vcom_offset(-44)

    mirror_v(false)
    mirror_h(false)
    rotation(0)
    vert_refresh_dir(NORM)
    subpix_order(RGB)
    horiz_refresh_dir(NORM)

    color_depth(16)

    clk_div(1)
    frame_rate(70)

    gamma_ctrl_ena(false)
    gamma_fixed_curve(2_2)                      ' param ignored; for symbolic purpose only
    gamma_tbl_neg(@_gammatbl_neg)
    gamma_tbl_pos(@_gammatbl_pos)

    draw_area(0, 0, 239, 319)

' xxx todo
    ' com.wrbyte_cmd($34) ' tearing effect off
    'com.wrbyte_cmd($35) ' tearing effect on
    'com.wrbyte_cmd($b4) ' display inversion
    'com.wrbyte_dat($00)
    com.wrbyte_cmd(core.DFUNCTR) ' display function control
    com.wrbyte_dat($0a)
    com.wrbyte_dat($82)
    com.wrbyte_dat($27)
    com.wrbyte_dat($00)
' xxx

    powered(true)
    visibility(NORMAL)

PUB preset_hiletgo_2p4_320x240_land_up()
' HiLetGo 2.4"
'   Landscape (320x * 240y), up (K1 button to left)
    defaults()
    set_dims(320, 240)
    draw_area(0, 0, _disp_xmax, _disp_ymax)
    subpix_order(BGR)
    mirror_h(false)
    mirror_v(false)
    rotation(1)

PUB preset_hiletgo_2p4_320x240_land_down()
' HiLetGo 2.4"
'   Landscape (320x * 240y), down (K1 button to right)
    defaults()
    set_dims(320, 240)
    draw_area(0, 0, _disp_xmax, _disp_ymax)
    subpix_order(BGR)
    mirror_h(true)
    mirror_v(true)
    rotation(1)

PUB preset_hiletgo_2p4_240x320_port_up()
' HiLetGo 2.4"
'   Portrait (240x * 320y), up (K1 button to top)
    defaults()
    set_dims(240, 320)
    draw_area(0, 0, _disp_xmax, _disp_ymax)
    subpix_order(BGR)
    mirror_h(true)
    mirror_v(false)
    rotation(0)

PUB preset_hiletgo_2p4_240x320_port_down()
' HiLetGo 2.4"
'   Portrait (240x * 320y), up (K1 button to bottom)
    defaults()
    set_dims(240, 320)
    draw_area(0, 0, _disp_xmax, _disp_ymax)
    subpix_order(BGR)
    mirror_h(false)
    mirror_v(true)
    rotation(0)

PUB stop()
' Power off the display, and stop the engine
    powered(false)
    com.deinit()

PUB bitmap(ptr_bmap, sx, sy, ex, ey) | nr_words
' Draw bitmap
'   ptr_bmap: pointer to bitmap data
'   (sx, sy): upper-left corner of bitmap
'   (ex, ey): lower-right corner of bitmap
'   nr_words: number of 16-bit words to read/draw from bitmap
    draw_area(sx, sy, ex, ey)
    nr_words := 1 #> ( (ex-sx) * (ey-sy) ) / BYTESPERPX
    com.wrbyte_cmd(core.RAMWR)
    com.wrblkword_msbf(ptr_bmap, nr_words)

PUB box(x1, y1, x2, y2, color, filled) | xt, yt
' Draw a box from (x1, y1) to (x2, y2) in color, optionally filled
    xt := ||(x2-x1)+1
    yt := ||(y2-y1)+1
    if (filled)
        draw_area(x1, y1, x2, y2)
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, (yt * xt))
    else
        draw_area(x1, y1, x2, y1)               ' top
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, xt)

        draw_area(x1, y2, x2, y2)               ' bottom
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, xt)

        draw_area(x1, y1, x1, y2)               ' left
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, yt)

        draw_area(x2, y1, x2, y2)               ' right
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, yt)

PUB clear()
' Clear display
    draw_area(0, 0, _disp_xmax, _disp_ymax)
    com.wrbyte_cmd(core.RAMWR)
    com.wrwordx_dat(_bgcolor, _buff_sz)

PUB clk_div(cdiv)
' Set LCD clock divisor
'   Valid values: 1, 2, 4, 8
    _frmctr1[FCLK_DIV] := (>|(1 #> cdiv <# 8)-1)
    com.wrbyte_cmd(core.FRMCTR1)
    com.wrbyte_dat(_frmctr1[FCLK_DIV])
    com.wrbyte_dat(_frmctr1[FRM_RT])

PUB color_depth(cbpp)
' Set display color depth, in bits per pixel
'   Valid values: 16, 18
    if (cbpp == 16)
        _colmod := $55                          ' 16bpp
    else
        _colmod := $66                          ' 18bpp

    com.wrbyte_cmd(core.COLMOD)
    com.wrbyte_dat(_colmod)

PUB draw_area(x1, y1, x2, y2) | x, y, cmd_pkt[2]
' Set drawing area for subsequent drawing command(s)
    if (x2 < x1)                                ' x2 must be greater than x1
        x := x2                                 ' if it isn't, swap them
        x2 := x1
        x1 := x
    if (y2 < y1)                                ' same as above, for y2, y1
        y := y2
        y2 := y1
        y1 := y

    cmd_pkt.byte[0] := x1.byte[1]
    cmd_pkt.byte[1] := x1.byte[0]
    cmd_pkt.byte[2] := x2.byte[1]
    cmd_pkt.byte[3] := x2.byte[0]
    cmd_pkt.byte[4] := y1.byte[1]
    cmd_pkt.byte[5] := y1.byte[0]
    cmd_pkt.byte[6] := y2.byte[1]
    cmd_pkt.byte[7] := y2.byte[0]

    com.wrbyte_cmd(core.CASET)
    com.wrblock_dat(@cmd_pkt.byte[0], 4)

    com.wrbyte_cmd(core.PASET)
    com.wrblock_dat(@cmd_pkt.byte[4], 4)

PUB frame_rate(frate): curr_frate
' Set LCD maximum frame rate, in Hz
'   Valid values: 61, 63, 65, 68, 70, 73, 76, 79, 83, 86, 90, 95, 100, 106, 112, 119
'       (clamped to range; values are calculated to the nearest match)
'   NOTE: This setting only affects the display when operating in NORMAL mode
    _frmctr1[FRM_RT] := (16 - ((( (61 #> frate <# 119) * 1_000) / 3_800) - 16))
    com.wrbyte_cmd(core.FRMCTR1)
    com.wrbyte_dat(_frmctr1[FCLK_DIV])
    com.wrbyte_dat(_frmctr1[FRM_RT])

PUB gamma_ctrl_ena(state)
' Enable 3-gamma control
'   Valid values: TRUE (non-zero), FALSE (0)
    _g3ctrl := (%10 | ((state <> 0) & 1))
    com.wrbyte_cmd(core.GM3CTRL)
    com.wrbyte_dat(_g3ctrl)

PUB gamma_fixed_curve(preset)
' Set gamma curve preset
'   NOTE: Parameter is ignored; for API compatibility with other drivers
    com.wrbyte_cmd(core.GAMMASET)
    com.wrbyte_dat($01)

PUB gamma_tbl_neg(ptr_buff)
' Modify gamma table (negative polarity)
    com.wrbyte_cmd(core.GMCTRN1)
    com.wrblock_dat(ptr_buff, 15)

PUB gamma_tbl_pos(ptr_buff)
' Modify gamma table (positive polarity)
    com.wrbyte_cmd(core.GMCTRP1)
    com.wrblock_dat(ptr_buff, 15)

PUB gvdd_voltage(v)
' Set GVDD level, in millivolts
'   (reference level for VCOM and grayscale voltage level)
'   Valid values: 3_000..6_000 (rounded to nearest 50mV)
    v := (( (3_000 #> v <# 6_000) / 50) - 57)
    com.wrbyte_cmd(core.PWCTR1)
    com.wrbyte_cmd(v)

PUB horiz_refresh_dir(mode)
' Set panel horizontal refresh direction
'   (refresh direction relative to panel's top-left (0, 0) location)
'   NORM (0): normal
'   INV (1): inverted
    mode := ((NORM #> mode <# INV) << core.MH)

    _madctl := ((_madctl & core.MH_MASK) | mode)
    com.wrbyte_cmd(core.MADCTL)
    com.wrbyte_dat(_madctl)

PUB invert_colors(state)
' Invert display colors
'   Valid values:
'       TRUE (non-zero), FALSE (0)
    com.wrbyte_cmd(core.INVOFF + ((state <> 0 ) & 1))

PUB line(x1, y1, x2, y2, color) | sx, sy, ddx, ddy, err, e2
' Draw line from (x1, y1) to (x2, y2), in color
    if (x1 == x2)
        draw_area(x1, y1, x1, y2)           ' vertical
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, (||(y2-y1))+1)
        return
    if (y1 == y2)
        draw_area(x1, y1, x2, y1)           ' horizontal
        com.wrbyte_cmd(core.RAMWR)
        com.wrwordx_dat(color, (||(x2-x1))+1)
        return

    { Bresenham's line algorithm }
    ddx := ||(x2-x1)
    ddy := ||(y2-y1)
    err := (ddx-ddy)

    sx := -1
    if (x1 < x2)
        sx := 1

    sy := -1
    if (y1 < y2)
        sy := 1

    repeat until ((x1 == x2) and (y1 == y2))
        plot(x1, y1, color)
        e2 := (err << 1)

        if (e2 > -ddy)
            err -= ddy
            x1 += sx

        if (e2 < ddx)
            err += ddx
            y1 += sy

PUB mirror_h(state)
' Mirror display, horizontally
'   Valid values:
'       TRUE (non-zero), FALSE (0)
    state := (((state <> 0) & 1) << core.MX)

    _madctl := ((_madctl & core.MX_MASK) | state)
    com.wrbyte_cmd(core.MADCTL)
    com.wrbyte_dat(_madctl)

PUB mirror_v(state)
' Mirror display, vertically
'   Valid values:
'       TRUE (-1 or 1), FALSE (0)
    state := (((state <> 0) & 1) << core.MY)

    _madctl := ((_madctl & core.MY_MASK) | state)
    com.wrbyte_cmd(core.MADCTL)
    com.wrbyte_dat(_madctl)

PUB plot(x, y, color) | cmd_pkt
' Plot pixel at (x, y) in color (direct to display)
    if ((x < 0) or (x > _disp_xmax) or (y < 0) or (y > _disp_ymax))
        return                                  ' coords out of bounds, ignore
    cmd_pkt.byte[0] := color.byte[1]
    cmd_pkt.byte[1] := color.byte[0]

    com.wrbyte_cmd(core.CASET)
    com.wrwordx_dat(x, 2)
    com.wrbyte_cmd(core.PASET)
    com.wrwordx_dat(y, 2)

    com.wrbyte_cmd(core.RAMWR)
    com.wrblock_dat(@cmd_pkt, 2)

PUB powered(state)
' Enable display power
'   Valid values:
'       TRUE (non-zero), FALSE (0)
    if (state)
        com.wrbyte_cmd(core.SLPOUT)
        time.msleep(60)
        com.wrbyte_cmd(core.DISPON)
    else
        com.wrbyte_cmd(core.DISPOFF)
        com.wrbyte_cmd(core.SLPIN)

PUB reset()
' Reset the display controller
    if (lookdown(_RESET: 0..31))                ' perform hard reset, if
        dira[_RESET] := 1                       '   I/O pin is defined
        outa[_RESET] := 1
        time.msleep(1)
        outa[_RESET] := 0
        time.msleep(10)
        outa[_RESET] := 1
        time.msleep(120)
    else                                        ' if not, just soft-reset
        com.wrbyte_cmd(core.SWRESET)
        time.msleep(5)

PUB rotation(state)
' Rotate display
'   Valid values: TRUE (non-zero), FALSE (0)
    state := (((state <> 0) & 1) << core.MV)

    _madctl := ((_madctl & core.MV_MASK) | state)
    com.wrbyte_cmd(core.MADCTL)
    com.wrbyte_dat(_madctl)

#ifdef GFX_DIRECT
PUB scroll_up_fs(px)
' dummy method
#endif

PUB show()
' dummy method for compatibility with other drivers

PUB subpix_order(order)
' Set subpixel color order
'   Valid values:
'       RGB (0): Red-Green-Blue order
'       BGR (1): Blue-Green-Red order
    order := ((RGB #> order <# BGR) << core.BGR)

    _madctl := ((_madctl & core.BGR_MASK) | order)
    com.wrbyte_cmd(core.MADCTL)
    com.wrbyte_dat(_madctl)

PUB vcomh_voltage(v)
' Set VCOMH voltage, in millivolts
'   Valid values: 2_700..5_875 (rounded to nearest 25mV; default: 3_925)
    _vmctrl1[VMH] := (( (2_700 #> v <# 5_875) - 2700) / 25)
    com.wrbyte_cmd(core.VMCTR1)
    com.wrbyte_dat(_vmctrl1[VMH])
    com.wrbyte_dat(_vmctrl1[VML])

PUB vcoml_voltage(v)
' Set VCOML voltage, in millivolts
'   Valid values: -2_500..0 (rounded to nearest 25mV; POR: -1_000)
    _vmctrl1[VML] := (((-2_500 #> v <# 0) + 2_500) / 25)
    com.wrbyte_cmd(core.VMCTR1)
    com.wrbyte_dat(_vmctrl1[VMH])
    com.wrbyte_dat(_vmctrl1[VML])

PUB vcom_offset(v)
' Set VCOMH/VCOML offset, in millivolts
'   Valid values: -63..63 (clamped to range; POR: 0)
    _vcomoffs := ((-63 #> v <# 63) + 64)
    com.wrbyte_cmd(core.VMCTR2)
    com.wrbyte_dat(_vcomoffs | core.SETNVM)

PUB vert_refresh_dir(mode)
' Set panel vertical refresh direction
'   (refresh direction relative to panel's top-left (0, 0) location)
'   NORM (0): normal
'   INV (1): inverted
    mode := ((NORM #> mode <# INV) << core.ML)

    _madctl := ((_madctl & core.ML_MASK) | mode)
    com.wrbyte_cmd(core.MADCTL)
    com.wrbyte_dat(_madctl)

PUB vgh_step_factor(fact)
' Set step-up factor for VGH operating voltage (VCI * n)
'   Valid values: 6, 7 (clamped to range)
    fact := (lookdownz( (6 #> fact <# 7): 7, 6) << 1)

    _pwr_ctrl2 := ((_pwr_ctrl2 & core.VGH_MASK) | fact)
    com.wrbyte_cmd(core.PWCTR2)
    com.wrbyte_dat(_pwr_ctrl2)

PUB vgl_step_factor(fact)
' Set step-up factor for VGL operating voltage (VCI * n)
'   Valid values: 3, 4 (clamped to range)
    fact := lookdownz( (3 #> fact <# 4): 4, 3)

    _pwr_ctrl2 := ((_pwr_ctrl2 & core.VGH_MASK) | fact)
    com.wrbyte_cmd(core.PWCTR2)
    com.wrbyte_dat(_pwr_ctrl2)

PUB visibility(mode)
' Set display visibility
'   Valid values:
'       ALL_OFF/OFF (0), NORMAL/ON (1), ALL_ON (3)
'   Any other value is ignored
'   NOTE: Does not affect the display RAM contents
    case ||(mode)
        OFF:
            com.wrbyte_cmd(core.DISPOFF)
        ON:
            com.wrbyte_cmd(core.ETMOD)
            com.wrbyte_dat(core.GDR_NORM)
            com.wrbyte_cmd(core.DISPON)
        ALL_ON:
            com.wrbyte_cmd(core.ETMOD)
            com.wrbyte_dat(core.GDR_VGH)

DAT

    _gammatbl_neg   byte    $00, $25, $27, $05
                    byte    $10, $09, $3a, $78
                    byte    $4d, $05, $18, $0d
                    byte    $38, $3a, $1f

    _gammatbl_pos   byte    $1f, $1a, $18, $0a
                    byte    $0f, $06, $45, $87
                    byte    $32, $0a, $07, $02
                    byte    $07, $05, $00

DAT
{
Copyright 2024 Jesse Burt

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}