lcddrvce.h

#include <lcddrvce.h>

The lcddrvce library is used for interacting with the Sitronix ST7789 LCD controller.

Overview

This library exposes interfaces to send any supported command to the LCD (this excludes read commands, which don’t work reliably on CE hardware).

Communication with the LCD controller is done over an SPI connection; however, the SPI hardware is also used to communicate with the ARM coprocessor on Python models. As such, the SPI hardware is not always set up properly to communicate with the LCD controller, and this library exists to provide a reliable and performant interface to the LCD across calculator models.

For additional information about the LCD controller and its commands, check out the documentation on WikiTI.

Library Initialization

The lcd_Init and lcd_Cleanup functions provide reference-counted initialization and cleanup of the SPI configuration. That means multiple calls to lcd_Init() are allowed, and the SPI hardware is restored to its original settings only after the same number of calls to lcd_Cleanup(). Since the configuration is set differently than the OS’s default settings for performance reasons, it’s not allowed to power off the calculator without cleaning up the library first. This means if calling certain functions like os_GetKey which can auto-power-down the calculator, either the LCD library should be cleaned up or auto-power-down should be disabled with os_DisableAPD(). When using this library as part of another library’s implementation and performance is not critical, it’s safest to call both lcd_Init() and lcd_Cleanup() each time commands need to be sent. That way, users of the library will be able to cleanup the SPI configuration whenever they need to.

API Documentation

This is a library for interfacing with the calculator’s LCD panel. It provides the ability to send direct commands over SPI, and convenience functions are provided for common commands.

Author

Brendan “calc84maniac” Fletcher

Defines

LCD_SIZEDCMD(cmd, size)

Converts a command name and size into a literal for use with lcd_SendSizedCommandRaw(), lcd_SendSizedCommandBytes(), or lcd_SendSizedCommandWords().

The LCD_CMD_ prefix is automatically taken care of.

For example, LCD_SIZEDCMD(VSCRDEF, 3) is used to send LCD_CMD_VSCRDEF with 3 parameters.

Parameters
  • cmd[in] Command name without LCD_CMD_ prefix

  • size[in] Parameters size in bytes or words (max 255)

LCD_PARAM16(param)

Converts a 16-bit parameter to big endian.

This is only needed when storing 16-bit parameters in a structure for use with lcd_SendCommandRaw() or lcd_SendParamsRaw(). Parameters sent using lcd_SendCommandWords() or specific command macros will be converted to big endian automatically.

lcd_SendCommandRaw(cmd, size, params)

Sends a command, given a pointer to its raw parameters.

Parameters
  • cmd[in] Command name without LCD_CMD_ prefix

  • size[in] Parameter data size in bytes (maximum 255)

  • params[in] Pointer to raw parameter data

Returns

Pointer following raw parameter data

lcd_SendCommandBytes(cmd, size, ...)

Sends a command with an arbitrary number of byte parameters.

Parameters
  • cmd[in] Command name without LCD_CMD_ prefix

  • size[in] Number of parameters (maximum 255)

  • ...[in] One function parameter for each byte parameter

lcd_SendCommandWords(cmd, size, ...)

Sends a command with an arbitrary number of 16-bit word parameters.

The parameters should be passed as their actual values, and are converted to big endian when transferred over SPI.

Parameters
  • cmd[in] Command name without LCD_CMD_ prefix

  • size[in] Number of parameters (maximum 255)

  • ...[in] One function parameter for each word parameter

lcd_SetInvertedMode(on)

Enables or disables pixel color inversion.

Parameters
  • on[in] Boolean indicating whether to enable inversion

lcd_SetDisplayEnable(on)

Enables or disables image display.

When disabled, displays a blank (white) image, regardless of the contents of LCD RAM.

Parameters
  • on[in] Boolean indicating whether image display should be on

lcd_SetSleepMode(on)

Enables or disables Sleep Mode.

Parameters
  • on[in] Boolean indicating whether to enable sleep mode

lcd_SetPartialMode(on)

Enables or disables Partial Mode.

This mode restricts image display to only a subset of the scanlines, with the remaining lines showing as white or black.

Parameters
  • on[in] Boolean indicating whether to enable partial mode

lcd_SetIdleMode(on)

Enables or disables Idle Mode.

When enabled, each color component of every pixel is rounded to 0 or 63, for 8 displayable colors total (Black, White, Red, Green, Blue, Cyan, Magenta, Yellow).

Parameters
  • on[in] Boolean indicating whether to enable idle mode

lcd_SetInterlacedMode(on)

Enables or disables screen interlacing.

When enabled, the left side of the frame is displayed on even-indexed vertical scanlines, and the right side of the frame is displayed on odd-indexed vertical scanlines.

Parameters
  • on[in] Boolean indicating whether to enable interlacing

lcd_SetScrollArea(TFA, VSA, BFA)

Sets the vertical scroll area definition.

Note

The sum of all three parameters should be 320.

Parameters
  • TFA[in] Number of lines in top fixed area, between 0 and 320

  • VSA[in] Number of lines in vertical scroll area, between 0 and 320

  • BFA[in] Number of lines in bottom fixed area, between 0 and 320

lcd_SetScrollAddress(addr)

Sets the vertical scroll start address.

Note

In typical usage, this address should be in the range [TFA, 320-BFA) so no lines are repeated. Whenever a displayed line address within the vertical scroll area would be at least 320-BFA, it will have (320-BFA)-TFA subtracted from it to cause wrapping within that range.

Parameters
  • addr[in] The source line to display at the start of the vertical scroll area

lcd_SetPartialArea(PSL, PEL)

Sets the start and end lines (inclusive) for the displayed area in Partial Mode.

Note

If the start line is greater than the end line, the displayed area wraps around.

Parameters
  • PSL[in] Partial start line, between 0 and 319

  • PEL[in] Partial end line, between 0 and 319

lcd_SetPartialControl(param)

Sets Partial Mode settings.

Can be used to set the color of lines outside the partial display area, as well as configure interval scan for those lines.

LCD_PARCTRL_DEFAULT can be used to restore the default settings.

Parameters
  • param[in] A bitwise OR of each field from lcd_parctrl

lcd_SetRamAccessOrder(param)

Sets the RAM access order flags.

These flags are useful for changing the order pixels are copied to the LCD RAM, including copying in column-major order by setting LCD_MV, which can help avoid screen tearing.

LCD_MADCTL_DEFAULT can be used to restore the default settings.

Note

Often, it makes sense to start with LCD_MADCTL_DEFAULT and then XOR any flags that need to be changed.

Parameters
  • param[in] A bitwise OR of flags from lcd_madctl

lcd_SetColumnAddress(XS, XE)

Sets the column address range (inclusive) for copying pixels to the LCD RAM.

The valid range depends on whether the configured RAM access order is row major or column major.

Parameters
  • XS[in] Column start address, between 0 and 319/239

  • XE[in] Column end address, between 0 and 319/239

lcd_SetRowAddress(YS, YE)

Sets the row address range (inclusive) for copying pixels to the LCD RAM.

The valid range depends on the configured RAM access order is row major or column major.

Parameters
  • YS[in] Row start address, between 0 and 239/319

  • YE[in] Row end address, between 0 and 239/319

lcd_StartPixelWrite()

Starts a pixel write operation, resetting the RAM pointer to the start of the column/row address range.

Pixels can be sent as raw parameter data with lcd_SendParamsRaw() until issuing another command. To continue from the next pixel after issuing another command, use lcd_ContinuePixelWrite().

Note

The RAM interface must first be set to SPI with lcd_SetRamInterface() or lcd_SetRamControl().

lcd_ContinuePixelWrite()

Continues a pixel write operation without resetting the RAM pointer.

Pixels can be sent as raw parameter data with lcd_SendParamsRaw() until issuing another command. To continue from the next pixel after issuing another command, this command can be used again.

Note

The RAM interface must first be set to SPI with lcd_SetRamInterface() or lcd_SetRamControl().

lcd_SetPixelFormat(param)

Sets the pixel formats for SPI and RGB interfaces.

LCD_COLMOD_DEFAULT can be used to restore the default settings.

Parameters
  • param[in] A bitwise OR of each field from lcd_colmod

lcd_SetRamInterface(param)

Sets the RAM interface and display mode settings.

LCD_RAMCTRL1_DEFAULT can be used to restore the default settings.

Parameters
  • param[in] A bitwise OR of each field from lcd_ramctrl1

lcd_SetRamControl(param1, param2)

Sets all RAM control settings.

LCD_RAMCTRL1_DEFAULT and LCD_RAMCTRL2_DEFAULT can be used to restore the default settings.

Parameters
  • param1[in] A bitwise OR of each field from lcd_ramctrl1

  • param2[in] A bitwise OR of each field from lcd_ramctrl2

lcd_SetGateControl(param)

Sets gate control flags.

This overrides any previous setting of lcd_SetInterlacedMode(), and vice versa.

LCD_GATECTRL_DEFAULT can be used to restore the default setting.

Parameters
lcd_SetInvertedSettings(param)

Sets inverted settings flags.

These flags invert the effects of various other settings.

LCD_LCMCTRL_DEFAULT can be used to restore the default settings.

Note

Often, it makes sense to start with LCD_LCMCTRL_DEFAULT and then XOR any flags that need to be inverted.

Parameters
  • param[in] A bitwise OR of flags from lcd_lcmctrl

lcd_SetNormalFrameRateControl(param)

Sets frame rate control settings for Normal Mode.

LCD_FRCTRL_DEFAULT can be used to restore the default setting.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • param[in] A bitwise OR of each field from lcd_frctrl

lcd_SetFrameRateDivider(DIV)

Sets the frame rate clock divider and disables separate frame rate control.

To enable separate frame rate control as well, use lcd_EnableDividedSeparateFrameRateControl().

LCD_DIV_DEFAULT can be used to restore the default setting.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • DIV[in] A clock divider constant from lcd_frctrl1

lcd_EnableSeparateFrameRateControl(idle, partial)

Enables and sets separate frame rate control settings for Idle Mode and Partial Mode.

Also resets the frame rate divider to the default. To set the frame rate divider as well, use lcd_EnableDividedSeparateFrameRateControl().

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • idle[in] A bitwise OR of each field from lcd_frctrl to be used in Idle Mode

  • partial[in] A bitwise OR of each field from lcd_frctrl to be used in Partial Mode

lcd_EnableDividedSeparateFrameRateControl(DIV, idle, partial)

Enables and sets separate frame rate control settings for Idle Mode and Partial Mode, with an additional clock divider.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • DIV[in] A clock divider constant from lcd_frctrl1.

  • idle[in] A bitwise OR of each field from lcd_frctrl to be used in Idle Mode

  • partial[in] A bitwise OR of each field from lcd_frctrl to be used in Partial Mode

lcd_DisableSeparateFrameRateControl()

Disables separate frame rate control settings for Idle Mode and Partial Mode.

Also resets the frame rate divider to the default. To avoid resetting the divider, use lcd_SetFrameRateDivider() instead.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

lcd_SetNormalPorchControl(BP, FP)

Sets porch control settings for Normal Mode.

LCD_BP_DEFAULT and LCD_FP_DEFAULT can be used to restore the default settings.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • BPA[in] Number of lines in back porch, between 1 and 127. Used only with LCD_DM_MCU or LCD_DM_VSYNC

  • FPA[in] Number of lines in front porch, between 1 and 127. Used only with LCD_DM_MCU

lcd_SetNormalBackPorchControl(BPA)

Sets only the back porch control setting for Normal Mode.

LCD_BP_DEFAULT can be used to restore the default setting.

Note

This setting is most useful when setting LCD_DM_VSYNC in lcd_SetRamInterface(), because the front porch setting is not used in that mode.

Parameters
lcd_EnableSeparatePorchControl(BPA, FPA, BPB, FPB, BPC, FPC)

Enables and sets separate porch control for Idle Mode and Partial Mode.

Requires specifying porch settings for Normal Mode as well.

LCD_BP_DEFAULT and LCD_FP_DEFAULT can be used to specify default settings for any mode.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • BPA[in] Number of lines in Normal Mode back porch, between 1 and 127

  • FPA[in] Number of lines in Normal Mode front porch, between 1 and 127

  • BPB[in] Number of lines in Idle Mode back porch, a multiple of 4 between 4 and 60

  • FPB[in] Number of lines in Idle Mode front porch, a multiple of 4 between 4 and 60

  • BPC[in] Number of lines in Partial Mode back porch, a multiple of 4 between 4 and 60

  • FPC[in] Number of lines in Partial Mode front porch, a multiple of 4 between 4 and 60

lcd_DisableSeparatePorchControl(BPA, FPA)

Disables separate porch control for Idle Mode and Partial Mode.

Requires specifying porch settings for Normal Mode, which will then apply to all modes.

LCD_BP_DEFAULT and LCD_FP_DEFAULT can be used to restore the default settings.

Note

This setting only matters the LCD controller is using internal scan timing, that is, when using a setting other than LCD_DM_RGB in lcd_SetRamInterface().

Parameters
  • BPA[in] Number of lines in back porch, between 1 and 127

  • FPA[in] Number of lines in front porch, between 1 and 127

lcd_SetDigitalGamma(on)

Enables or disables digital gamma.

Digital gamma mappings can be set using lcd_SetDigitalGammaTableRed() and lcd_SetDigitalGammaTableBlue().

Parameters
  • on[in] Boolean indicating whether to enable digital gamma

lcd_SetDigitalGammaTableRed(table)

Sets the digital gamma mapping table for the Red component.

Note

With the default BGR settings, this table actually modifies the Blue component’s gamma. Also, due to a hardware quirk, the LSB of the input component is forced to 0 before indexing the table.

Parameters
  • table[in] A pointer to a 64-byte table, with the most significant 6 bits of each byte determining the output component value.

lcd_SetDigitalGammaTableBlue(table)

Sets the digital gamma mapping table for the Blue component.

Note

With the default BGR settings, this table actually modifies the Red component’s gamma. Also, due to a hardware quirk, the LSB of the input component is forced to 0 before indexing the table.

Parameters
  • table[in] A pointer to a 64-byte table, with the most significant 6 bits of each byte determining the output component value.

LCD_CMD_NOP

No operation.

LCD_CMD_SWRESET

Software reset.

LCD_CMD_SLPIN

Sleep in.

LCD_CMD_SLPOUT

Sleep out.

LCD_CMD_PTLON

Partial display mode on.

LCD_CMD_NORON

Normal display mode on.

LCD_CMD_INVOFF

Display inversion off.

LCD_CMD_INVON

Display inversion on.

LCD_CMD_GAMSET

Gamma set.

LCD_CMD_DISPOFF

Display off.

LCD_CMD_DISPON

Display on.

LCD_CMD_CASET

Column address set.

LCD_CMD_RASET

Row address set.

LCD_CMD_RAMWR

Memory write.

LCD_CMD_PTLAR

Partial area.

LCD_CMD_VSCRDEF

Vertical scrolling definition.

LCD_CMD_TEOFF

Tearing effect line off.

LCD_CMD_TEON

Tearing effect line on.

LCD_CMD_MADCTL

Memory data access control.

LCD_CMD_VSCSAD

Vertical scroll start address of RAM.

LCD_CMD_IDMOFF

Idle mode off.

LCD_CMD_IDMON

Idle mode on.

LCD_CMD_COLMOD

Interface pixel format.

LCD_CMD_RAMWRC

Write memory continue.

LCD_CMD_STE

Set tear scanline.

LCD_CMD_RAMCTRL

RAM control.

LCD_CMD_RGBCTRL

RGB interface control.

LCD_VBP_DEFAULT

TI-OS default for parameter byte 2 of LCD_CMD_RGBCTRL (defined as 5)

LCD_HBP_DEFAULT

TI-OS default for parameter byte 3 of LCD_CMD_RGBCTRL (defined as 20)

LCD_CMD_PORCTRL

Porch setting.

LCD_BP_DEFAULT

TI-OS default back porch for LCD_CMD_PORCTRL parameters (defined as 12)

LCD_FP_DEFAULT

TI-OS default front porch for LCD_CMD_PORCTRL parameters (defined as 12)

LCD_CMD_FRCTRL1

Frame rate control 1 (in partial mode/idle colors)

LCD_CMD_PARCTRL

Partial control.

LCD_CMD_GTADJ

Gate on timing adjustment.

LCD_CMD_DGMEN

Digital gamma enable.

LCD_CMD_POWSAVE

Power saving mode.

LCD_CMD_DLPOFFSAVE

Display off power save.

LCD_CMD_LCMCTRL

LCM control.

LCD_CMD_IDSET

ID code setting.

LCD_CMD_VCMOFSET

VCOM offset set.

LCD_CMD_FRCTRL2

Frame rate control in normal mode.

LCD_CMD_PVGAMCTRL

Positive voltage gamma control.

LCD_CMD_NVGAMCTRL

Negative voltage gamma control.

LCD_CMD_DGMLUTR

Digital gamma lookup table for red.

LCD_CMD_DGMLUTB

Digital gamma lookup table for blue.

LCD_CMD_GATECTRL

Gate control.

LCD_CMD_EQCTRL

Equalize time control.

Typedefs

typedef enum lcd_gamset lcd_gamset_t

Parameter values for LCD_CMD_GAMSET.

typedef enum lcd_madctl lcd_madctl_t

Parameter flags for LCD_CMD_MADCTL.

typedef enum lcd_pxlfmt lcd_pxlfmt_t

Pixel format field values.

typedef enum lcd_colmod lcd_colmod_t

Parameter fields for LCD_CMD_COLMOD.

typedef enum lcd_ramctrl1 lcd_ramctrl1_t

Fields for parameter byte 1 of LCD_CMD_RAMCTRL.

typedef enum lcd_ramctrl2 lcd_ramctrl2_t

Fields for parameter byte 2 of LCD_CMD_RAMCTRL.

typedef enum lcd_rgbctrl lcd_rgbctrl_t

Flags and fields for parameter byte 1 of LCD_CMD_RGBCTRL.

typedef enum lcd_porctrl lcd_porctrl_t

Values for parameter byte 3 of LCD_CMD_PORCTRL.

typedef enum lcd_frctrl1 lcd_frctrl1_t

Fields for parameter byte 1 of LCD_CMD_FRCTRL1.

typedef enum lcd_parctrl lcd_parctrl_t

Parameter fields for LCD_CMD_PARCTRL.

typedef enum lcd_dgmen lcd_dgmen_t

Parameter values for LCD_CMD_DGMEN.

typedef enum lcd_lcmctrl lcd_lcmctrl_t

Parameter flags for LCD_CMD_LCMCTRL.

typedef enum lcd_frctrl lcd_frctrl_t

Parameter fields for LCD_CMD_FRCTRL2 and parameter bytes 2 and 3 of LCD_CMD_FRCTRL1.

typedef enum lcd_gatectrl_nl lcd_gatectrl_nl_t

Values for parameter byte 1 of LCD_CMD_GATECTRL.

typedef enum lcd_gatectrl_scn lcd_gatectrl_scn_t

Values for parameter byte 2 of LCD_CMD_GATECTRL.

typedef enum lcd_gatectrl lcd_gatectrl_t

Values for parameter byte 3 of LCD_CMD_GATECTRL.

Enums

enum lcd_gamset

Parameter values for LCD_CMD_GAMSET.

Values:

enumerator LCD_GAM_2_2 = 1

Gamma 2.2.

enumerator LCD_GAM_1_8 = 2

Gamma 1.8.

enumerator LCD_GAM_2_5 = 4

Gamma 2.5.

enumerator LCD_GAM_1_0 = 8

Gamma 1.0.

enum lcd_madctl

Parameter flags for LCD_CMD_MADCTL.

Values:

enumerator LCD_MH = 1 << 2

Display data latch order (scan from bottom to top)

enumerator LCD_BGR = 1 << 3

BGR order (swap red and blue)

enumerator LCD_ML = 1 << 4

Line address order (scan from right to left)

enumerator LCD_MV = 1 << 5

Page/column order (RAM access is column major)

enumerator LCD_MX = 1 << 6

Column address order (RAM access from bottom to top)

enumerator LCD_MY = 1 << 7

Page address order (RAM access from right to left)

enumerator LCD_MADCTL_DEFAULT = LCD_BGR

TI-OS default parameters.

enum lcd_pxlfmt

Pixel format field values.

Values:

enumerator LCD_PXLFMT_12BPP = 3

12 bits per pixel (SPI only)

enumerator LCD_PXLFMT_16BPP = 5

16 bits per pixel

enumerator LCD_PXLFMT_18BPP = 6

18 bits per pixel

enumerator LCD_PXLFMT_MASK = 7

Bitmask for PXLFMT field.

enum lcd_colmod

Parameter fields for LCD_CMD_COLMOD.

Values:

enumerator LCD_SPI_12BPP = LCD_PXLFMT_12BPP << 0

12 bits per pixel over SPI interface

enumerator LCD_SPI_16BPP = LCD_PXLFMT_16BPP << 0

16 bits per pixel over SPI interface

enumerator LCD_SPI_18BPP = LCD_PXLFMT_18BPP << 0

18 bits per pixel over SPI interface

enumerator LCD_RGB_16BPP = LCD_PXLFMT_16BPP << 4

16 bits per pixel over RGB interface

enumerator LCD_RGB_18BPP = LCD_PXLFMT_18BPP << 4

18 bits per pixel over RGB interface

enumerator LCD_SPI_MASK = LCD_PXLFMT_MASK << 0

Bitmask for SPI field.

enumerator LCD_RGB_MASK = LCD_PXLFMT_MASK << 4

Bitmask for RGB field.

enumerator LCD_SPI_DEFAULT = LCD_SPI_18BPP

TI-OS default SPI bits per pixel.

enumerator LCD_RGB_DEFAULT = LCD_RGB_18BPP

TI-OS default RGB bits per pixel.

enumerator LCD_COLMOD_DEFAULT = LCD_SPI_DEFAULT | LCD_RGB_DEFAULT

TI-OS default parameters.

enum lcd_ramctrl1

Fields for parameter byte 1 of LCD_CMD_RAMCTRL.

Values:

enumerator LCD_DM_MCU = 0 << 0

MCU display mode (internal timing)

enumerator LCD_DM_RGB = 1 << 0

RGB display mode (RGB interface timing)

enumerator LCD_DM_VSYNC = 2 << 0

VSYNC display mode (internal timing except for RGB interface VSYNC)

enumerator LCD_RAM_SPI = 0 << 4

RAM access over SPI interface.

enumerator LCD_RAM_RGB = 1 << 4

RAM access over RGB interface.

enumerator LCD_DM_MASK = 3 << 0

Bitmask for DM field.

enumerator LCD_RAM_MASK = 1 << 4

Bitmask for RAM field.

enumerator LCD_DM_DEFAULT = LCD_DM_RGB

TI-OS default display mode.

enumerator LCD_RAM_DEFAULT = LCD_RAM_RGB

TI-OS default RAM access.

enumerator LCD_RAMCTRL1_DEFAULT = LCD_DM_DEFAULT | LCD_RAM_DEFAULT

TI-OS default parameters.

enum lcd_ramctrl2

Fields for parameter byte 2 of LCD_CMD_RAMCTRL.

Values:

enumerator LCD_BUS_18BIT = 0 << 2

18-bit bus for RGB interface (use this on the CE)

enumerator LCD_BUS_6BIT = 1 << 2

6-bit bus for RGB interface (not used on the CE)

enumerator LCD_ENDIAN_BIG = 0 << 3

Big endian order for 16-bit pixels sent over SPI.

enumerator LCD_ENDIAN_LITTLE = 1 << 3

Little endian order for 16-bit pixels sent over SPI.

enumerator LCD_EPF_0 = 0 << 4

Expanded pixel format where component LSBs are set to 0.

enumerator LCD_EPF_1 = 1 << 4

Expanded pixel format where component LSBs are set to 1.

enumerator LCD_EPF_MSB = 2 << 4

Expanded pixel format where component LSBs are copied from the MSBs.

enumerator LCD_EPF_GREEN = 3 << 4

Expanded pixel format where component LSBs are copied from green LSB.

enumerator LCD_WEMODE_SPI_STOP = 0 << 6

Stop-at-end mode for SPI interface; after writing the last row and column, ignore further pixels.

enumerator LCD_WEMODE_SPI_WRAP = 1 << 6

Wrap-at-end mode for SPI interface; after writing the last row and column, wrap to the start.

enumerator LCD_WEMODE_RGB_WRAP = 0 << 7

Wrap-at-end mode for RGB interface; after writing the last row and column, wrap to the start.

enumerator LCD_WEMODE_RGB_STOP = 1 << 7

Stop-at-end mode for RGB interface; after writing the last row and column, ignore further pixels.

enumerator LCD_BUS_MASK = 1 << 2

Bitmask for BUS field.

enumerator LCD_ENDIAN_MASK = 1 << 3

Bitmask for ENDIAN field.

enumerator LCD_EPF_MASK = 3 << 4

Bitmask for EPF field.

enumerator LCD_WEMODE_SPI_MASK = 1 << 6

Bitmask for WEMODE_SPI field.

enumerator LCD_WEMODE_RGB_MASK = 1 << 7

Bitmask for WEMODE_RGB field.

enumerator LCD_BUS_DEFAULT = LCD_BUS_18BIT

TI-OS default RGB interface bus width.

enumerator LCD_ENDIAN_DEFAULT = LCD_ENDIAN_BIG

TI-OS default endian order for 16-bit pixels sent over SPI.

enumerator LCD_EPF_DEFAULT = LCD_EPF_GREEN

TI-OS default expanded pixel format.

enumerator LCD_WEMODE_SPI_DEFAULT = LCD_WEMODE_SPI_WRAP

TI-OS default wrap-at-end mode for SPI interface.

enumerator LCD_WEMODE_RGB_DEFAULT = LCD_WEMODE_RGB_STOP

TI-OS default wrap-at-end mode for RGB interface.

enumerator LCD_RAMCTRL2_DEFAULT = LCD_BUS_DEFAULT | LCD_ENDIAN_DEFAULT | LCD_EPF_DEFAULT | LCD_WEMODE_SPI_DEFAULT | LCD_WEMODE_RGB_DEFAULT

TI-OS default parameters.

enum lcd_rgbctrl

Flags and fields for parameter byte 1 of LCD_CMD_RGBCTRL.

Values:

enumerator LCD_EPL = 1 << 0

ENABLE signal polarity for RGB interface (set for low)

enumerator LCD_DPL = 1 << 1

DOTCLK signal polarity for RGB interface (set for falling edge)

enumerator LCD_HSPL = 1 << 2

HSYNC signal polarity for RGB interface (set for high active)

enumerator LCD_VSPL = 1 << 3

VSYNC signal polarity for RGB interface (set for high active)

enumerator LCD_RCM_DE = 2 << 5

Set RGB DE (Data Enable) mode.

enumerator LCD_RCM_HV = 3 << 5

Set RGB HV (HSYNC/VSYNC) mode.

enumerator LCD_WO = 1 << 7

Enable direct RGB mode, bypassing RAM.

enumerator LCD_RCM_MASK = 3 << 5

Mask for RCM field.

enumerator LCD_RCM_DEFAULT = 0 << 5

TI-OS default RGB control mode (functionally equivalent to LCD_RCM_DE)

enumerator LCD_RGBCTRL_DEFAULT = LCD_RCM_DEFAULT | LCD_EPL

TI-OS default parameters.

enum lcd_porctrl

Values for parameter byte 3 of LCD_CMD_PORCTRL.

Values:

enumerator LCD_PS_DISABLE = 0

Disable separate porch control.

enumerator LCD_PS_ENABLE = 1

Enable separate porch control.

enumerator LCD_PS_DEFAULT = LCD_PS_DISABLE

TI-OS default parameter.

enum lcd_frctrl1

Fields for parameter byte 1 of LCD_CMD_FRCTRL1.

Values:

enumerator LCD_DIV_1 = 0 << 0

Divide LCD internal pixel clock rate by 1 (10 MHz)

enumerator LCD_DIV_2 = 1 << 0

Divide LCD internal pixel clock rate by 2 (5 MHz)

enumerator LCD_DIV_4 = 2 << 0

Divide LCD internal pixel clock rate by 4 (2.5 MHz)

enumerator LCD_DIV_8 = 3 << 0

Divide LCD internal pixel clock rate by 8 (1.25 MHz)

enumerator LCD_FRS_DISABLE = 0 << 4

Disable separate frame rate control for Idle Mode and Partial Mode.

enumerator LCD_FRS_ENABLE = 1 << 4

Enable separate frame rate control for Idle Mode and Partial Mode.

enumerator LCD_DIV_MASK = 3 << 0

Bitmask for DIV field.

enumerator LCD_FRS_MASK = 1 << 4

Bitmask for FRS field.

enumerator LCD_DIV_DEFAULT = LCD_DIV_1

TI-OS default pixel clock divider.

enumerator LCD_FRS_DEFAULT = LCD_FRS_DISABLE

TI-OS default separate frame rate control setting.

enumerator LCD_FRCTRL1_DEFAULT = LCD_DIV_DEFAULT | LCD_FRS_DEFAULT

TI-OS default parameters.

enum lcd_parctrl

Parameter fields for LCD_CMD_PARCTRL.

Values:

enumerator LCD_ISC_NONE = 0 << 0

Interval scan mode disabled.

enumerator LCD_ISC_1 = 16 << 0

Non-display area is scanned every frame.

enumerator LCD_ISC_3 = 17 << 0

Non-display area is scanned every 3 frames.

enumerator LCD_ISC_5 = 18 << 0

Non-display area is scanned every 5 frames.

enumerator LCD_ISC_7 = 19 << 0

Non-display area is scanned every 7 frames.

enumerator LCD_ISC_9 = 20 << 0

Non-display area is scanned every 9 frames.

enumerator LCD_ISC_11 = 21 << 0

Non-display area is scanned every 11 frames.

enumerator LCD_ISC_13 = 22 << 0

Non-display area is scanned every 13 frames.

enumerator LCD_ISC_15 = 23 << 0

Non-display area is scanned every 15 frames.

enumerator LCD_ISC_17 = 24 << 0

Non-display area is scanned every 17 frames.

enumerator LCD_ISC_19 = 25 << 0

Non-display area is scanned every 19 frames.

enumerator LCD_ISC_21 = 26 << 0

Non-display area is scanned every 21 frames.

enumerator LCD_ISC_23 = 27 << 0

Non-display area is scanned every 23 frames.

enumerator LCD_ISC_25 = 28 << 0

Non-display area is scanned every 25 frames.

enumerator LCD_ISC_27 = 29 << 0

Non-display area is scanned every 27 frames.

enumerator LCD_ISC_29 = 30 << 0

Non-display area is scanned every 29 frames.

enumerator LCD_ISC_31 = 31 << 0

Non-display area is scanned every 31 frames.

enumerator LCD_NDL_WHITE = 0 << 7

Non-display area is displayed as white.

enumerator LCD_NDL_BLACK = 1 << 7

Non-display area is displayed as black.

enumerator LCD_ISC_MASK = 31 << 0

Bitmask for ISC field.

enumerator LCD_NDL_MASK = 1 << 7

Bitmask for NDL field.

enumerator LCD_ISC_DEFAULT = LCD_ISC_NONE

TI-OS default interval scan cycle setting.

enumerator LCD_NDL_DEFAULT = LCD_NDL_WHITE

TI-OS default non-display level setting.

enumerator LCD_PARCTRL_DEFAULT = LCD_ISC_DEFAULT | LCD_NDL_DEFAULT

TI-OS default parameters.

enum lcd_dgmen

Parameter values for LCD_CMD_DGMEN.

Values:

enumerator LCD_DGM_DISABLE = 0 << 2

Disable digital gamma.

enumerator LCD_DGM_ENABLE = 1 << 2

Enable digital gamma.

enumerator LCD_DGM_DEFAULT = LCD_DGM_DISABLE

TI-OS default digital gamma setting.

enum lcd_lcmctrl

Parameter flags for LCD_CMD_LCMCTRL.

Values:

enumerator LCD_XGS = 1 << 0

Set to invert the effect of LCD_GS.

enumerator LCD_XMV = 1 << 1

Set to invert the effect of LCD_MV.

enumerator LCD_XMH = 1 << 2

Set to invert the effect of LCD_MH.

enumerator LCD_XMX = 1 << 3

Set to invert the effect of LCD_MX.

enumerator LCD_XINV = 1 << 4

Set to invert the effect of LCD_CMD_INVOFF and LCD_CMD_INVON.

enumerator LCD_XBGR = 1 << 5

Set to invert the effect of LCD_BGR.

enumerator LCD_XMY = 1 << 6

Set to invert the effect of LCD_MY.

enumerator LCD_LCMCTRL_DEFAULT = LCD_XMV | LCD_XBGR

TI-OS default parameters.

enum lcd_frctrl

Parameter fields for LCD_CMD_FRCTRL2 and parameter bytes 2 and 3 of LCD_CMD_FRCTRL1.

Values:

enumerator LCD_RTN_250 = 0 << 0

250 pixel clocks per line (119 Hz with default porches).

Should not be used or internal RAM reads will fail.

enumerator LCD_RTN_266 = 1 << 0

266 pixel clocks per line (111 Hz with default porches)

enumerator LCD_RTN_282 = 2 << 0

282 pixel clocks per line (105 Hz with default porches)

enumerator LCD_RTN_298 = 3 << 0

282 pixel clocks per line (99 Hz with default porches)

enumerator LCD_RTN_314 = 4 << 0

314 pixel clocks per line (94 Hz with default porches)

enumerator LCD_RTN_330 = 5 << 0

330 pixel clocks per line (90 Hz with default porches)

enumerator LCD_RTN_346 = 6 << 0

346 pixel clocks per line (86 Hz with default porches)

enumerator LCD_RTN_362 = 7 << 0

362 pixel clocks per line (82 Hz with default porches)

enumerator LCD_RTN_378 = 8 << 0

378 pixel clocks per line (78 Hz with default porches)

enumerator LCD_RTN_394 = 9 << 0

394 pixel clocks per line (75 Hz with default porches)

enumerator LCD_RTN_410 = 10 << 0

410 pixel clocks per line (72 Hz with default porches)

enumerator LCD_RTN_426 = 11 << 0

426 pixel clocks per line (69 Hz with default porches)

enumerator LCD_RTN_442 = 12 << 0

442 pixel clocks per line (67 Hz with default porches)

enumerator LCD_RTN_458 = 13 << 0

458 pixel clocks per line (64 Hz with default porches)

enumerator LCD_RTN_474 = 14 << 0

474 pixel clocks per line (62 Hz with default porches)

enumerator LCD_RTN_490 = 15 << 0

490 pixel clocks per line (60 Hz with default porches)

enumerator LCD_RTN_506 = 16 << 0

506 pixel clocks per line (58 Hz with default porches)

enumerator LCD_RTN_522 = 17 << 0

522 pixel clocks per line (57 Hz with default porches)

enumerator LCD_RTN_538 = 18 << 0

538 pixel clocks per line (55 Hz with default porches)

enumerator LCD_RTN_554 = 19 << 0

554 pixel clocks per line (53 Hz with default porches)

enumerator LCD_RTN_570 = 20 << 0

570 pixel clocks per line (52 Hz with default porches)

enumerator LCD_RTN_586 = 21 << 0

586 pixel clocks per line (50 Hz with default porches)

enumerator LCD_RTN_602 = 22 << 0

602 pixel clocks per line (49 Hz with default porches)

enumerator LCD_RTN_618 = 23 << 0

618 pixel clocks per line (48 Hz with default porches)

enumerator LCD_RTN_634 = 24 << 0

634 pixel clocks per line (46 Hz with default porches)

enumerator LCD_RTN_650 = 25 << 0

650 pixel clocks per line (45 Hz with default porches)

enumerator LCD_RTN_666 = 26 << 0

666 pixel clocks per line (44 Hz with default porches)

enumerator LCD_RTN_682 = 27 << 0

682 pixel clocks per line (43 Hz with default porches)

enumerator LCD_RTN_698 = 28 << 0

698 pixel clocks per line (42 Hz with default porches)

enumerator LCD_RTN_714 = 29 << 0

714 pixel clocks per line (41 Hz with default porches)

enumerator LCD_RTN_730 = 30 << 0

730 pixel clocks per line (40 Hz with default porches)

enumerator LCD_RTN_746 = 31 << 0

746 pixel clocks per line (39 Hz with default porches)

enumerator LCD_NL_DOT = 0 << 5

Dot-based polarity inversion.

enumerator LCD_NL_COLUMN = 7 << 5

Column-based polarity inversion.

enumerator LCD_RTN_MASK = 31 << 0

Bitmask for RTN field.

enumerator LCD_NL_MASK = 7 << 5

Bitmask for NL field.

enumerator LCD_RTN_DEFAULT = LCD_RTN_490

TI-OS default pixel clocks per line.

enumerator LCD_NL_DEFAULT = LCD_NL_DOT

TI-OS default polarity inversion mode.

enumerator LCD_FRCTRL_DEFAULT = LCD_RTN_DEFAULT | LCD_NL_DEFAULT

TI-OS default parameters.

enum lcd_gatectrl_nl

Values for parameter byte 1 of LCD_CMD_GATECTRL.

Values:

enumerator LCD_GC_NL_8 = 0

8 physical lines in the display

enumerator LCD_GC_NL_16 = 1

16 physical lines in the display

enumerator LCD_GC_NL_24 = 2

24 physical lines in the display

enumerator LCD_GC_NL_32 = 3

32 physical lines in the display

enumerator LCD_GC_NL_40 = 4

40 physical lines in the display

enumerator LCD_GC_NL_48 = 5

48 physical lines in the display

enumerator LCD_GC_NL_56 = 6

56 physical lines in the display

enumerator LCD_GC_NL_64 = 7

64 physical lines in the display

enumerator LCD_GC_NL_72 = 8

72 physical lines in the display

enumerator LCD_GC_NL_80 = 9

80 physical lines in the display

enumerator LCD_GC_NL_88 = 10

88 physical lines in the display

enumerator LCD_GC_NL_96 = 11

96 physical lines in the display

enumerator LCD_GC_NL_104 = 12

104 physical lines in the display

enumerator LCD_GC_NL_112 = 13

112 physical lines in the display

enumerator LCD_GC_NL_120 = 14

120 physical lines in the display

enumerator LCD_GC_NL_128 = 15

128 physical lines in the display

enumerator LCD_GC_NL_136 = 16

136 physical lines in the display

enumerator LCD_GC_NL_144 = 17

144 physical lines in the display

enumerator LCD_GC_NL_152 = 18

152 physical lines in the display

enumerator LCD_GC_NL_160 = 19

160 physical lines in the display

enumerator LCD_GC_NL_168 = 20

168 physical lines in the display

enumerator LCD_GC_NL_176 = 21

176 physical lines in the display

enumerator LCD_GC_NL_184 = 22

184 physical lines in the display

enumerator LCD_GC_NL_192 = 23

192 physical lines in the display

enumerator LCD_GC_NL_200 = 24

200 physical lines in the display

enumerator LCD_GC_NL_208 = 25

208 physical lines in the display

enumerator LCD_GC_NL_216 = 26

216 physical lines in the display

enumerator LCD_GC_NL_224 = 27

224 physical lines in the display

enumerator LCD_GC_NL_232 = 28

232 physical lines in the display

enumerator LCD_GC_NL_240 = 29

240 physical lines in the display

enumerator LCD_GC_NL_248 = 30

248 physical lines in the display

enumerator LCD_GC_NL_256 = 31

256 physical lines in the display

enumerator LCD_GC_NL_264 = 32

264 physical lines in the display

enumerator LCD_GC_NL_272 = 33

272 physical lines in the display

enumerator LCD_GC_NL_280 = 34

280 physical lines in the display

enumerator LCD_GC_NL_288 = 35

288 physical lines in the display

enumerator LCD_GC_NL_296 = 36

296 physical lines in the display

enumerator LCD_GC_NL_304 = 37

304 physical lines in the display

enumerator LCD_GC_NL_312 = 38

312 physical lines in the display

enumerator LCD_GC_NL_320 = 39

320 physical lines in the display

enumerator LCD_GC_NL_DEFAULT = LCD_GC_NL_320

TI-OS default parameter.

enum lcd_gatectrl_scn

Values for parameter byte 2 of LCD_CMD_GATECTRL.

Values:

enumerator LCD_GC_SCN_0 = 0

Display starts at gate 0

enumerator LCD_GC_SCN_8 = 1

Display starts at gate 8

enumerator LCD_GC_SCN_16 = 2

Display starts at gate 16

enumerator LCD_GC_SCN_24 = 3

Display starts at gate 24

enumerator LCD_GC_SCN_32 = 4

Display starts at gate 32

enumerator LCD_GC_SCN_40 = 5

Display starts at gate 40

enumerator LCD_GC_SCN_48 = 6

Display starts at gate 48

enumerator LCD_GC_SCN_56 = 7

Display starts at gate 56

enumerator LCD_GC_SCN_64 = 8

Display starts at gate 64

enumerator LCD_GC_SCN_72 = 9

Display starts at gate 72

enumerator LCD_GC_SCN_80 = 10

Display starts at gate 80

enumerator LCD_GC_SCN_88 = 11

Display starts at gate 88

enumerator LCD_GC_SCN_96 = 12

Display starts at gate 96

enumerator LCD_GC_SCN_104 = 13

Display starts at gate 104.

enumerator LCD_GC_SCN_112 = 14

Display starts at gate 112.

enumerator LCD_GC_SCN_120 = 15

Display starts at gate 120.

enumerator LCD_GC_SCN_128 = 16

Display starts at gate 128.

enumerator LCD_GC_SCN_136 = 17

Display starts at gate 136.

enumerator LCD_GC_SCN_144 = 18

Display starts at gate 144.

enumerator LCD_GC_SCN_152 = 19

Display starts at gate 152.

enumerator LCD_GC_SCN_160 = 20

Display starts at gate 160.

enumerator LCD_GC_SCN_168 = 21

Display starts at gate 168.

enumerator LCD_GC_SCN_176 = 22

Display starts at gate 176.

enumerator LCD_GC_SCN_184 = 23

Display starts at gate 184.

enumerator LCD_GC_SCN_192 = 24

Display starts at gate 192.

enumerator LCD_GC_SCN_200 = 25

Display starts at gate 200.

enumerator LCD_GC_SCN_208 = 26

Display starts at gate 208.

enumerator LCD_GC_SCN_216 = 27

Display starts at gate 216.

enumerator LCD_GC_SCN_224 = 28

Display starts at gate 224.

enumerator LCD_GC_SCN_232 = 29

Display starts at gate 232.

enumerator LCD_GC_SCN_240 = 30

Display starts at gate 240.

enumerator LCD_GC_SCN_248 = 31

Display starts at gate 248.

enumerator LCD_GC_SCN_256 = 32

Display starts at gate 256.

enumerator LCD_GC_SCN_264 = 33

Display starts at gate 264.

enumerator LCD_GC_SCN_272 = 34

Display starts at gate 272.

enumerator LCD_GC_SCN_280 = 35

Display starts at gate 280.

enumerator LCD_GC_SCN_288 = 36

Display starts at gate 288.

enumerator LCD_GC_SCN_296 = 37

Display starts at gate 296.

enumerator LCD_GC_SCN_304 = 38

Display starts at gate 304.

enumerator LCD_GC_SCN_312 = 39

Display starts at gate 312.

enumerator LCD_GC_SCN_DEFAULT = LCD_GC_SCN_0

TI-OS default parameter.

enum lcd_gatectrl

Values for parameter byte 3 of LCD_CMD_GATECTRL.

Values:

enumerator LCD_GS = 1 << 0

Gate scan direction (scan from right to left)

enumerator LCD_SS = 1 << 1

Source scan direction (scan from bottom to top)

enumerator LCD_SM = 1 << 2

Interlaced scan mode.

enumerator LCD_TMG = 1 << 4

Gate mirror selection (local mirror for displays with fewer than 320 lines)

enumerator LCD_GATECTRL_DEFAULT = LCD_TMG

TI-OS default parameters.

Functions

void lcd_Init(void)

Initializes the LCD driver.

The first call to this function will reinitialize the SPI controller to target the LCD and prepare the SPI controller to send data.

Note

This must be called before any other function. Each call to this function must correspond to a call to lcd_Cleanup().

void lcd_Wait(void)

Waits for all previously queued commands and parameters to finish sending.

void lcd_Cleanup(void)

Uninitializes the LCD driver.

The last call to this function, corresponding to the first call to lcd_Init(), will disable the SPI controller. Implicitly calls lcd_Wait() in case there are commands in progress.

Note

This will not restore any changed LCD settings. If that is necessary, send commands to change them back to defaults.

const void *lcd_SendSizedCommandRaw(uint16_t sized_cmd, const void *params)

Sends a command, given a pointer to its raw parameters.

You can also use the lcd_SendCommandRaw() convenience macro to specify the command and the size of the parameters separately.

Parameters
  • sized_cmd[in] An LCD_SIZEDCMD literal, specifying parameter data size in bytes

  • params[in] Pointer to raw parameter data

Returns

Pointer following raw parameter data

const void *lcd_SendParamsRaw(size_t size, const void *params)

Sends only raw parameters to a previously sent command.

Most useful for sending pixel data after lcd_StartPixelWrite() or lcd_ContinuePixelWrite().

Parameters
  • size[in] Size of the raw parameters in bytes

  • params[in] Pointer to raw parameter data

Returns

Pointer following the raw parameter data.

void lcd_SendCommand(uint8_t cmd)

Sends a command with no parameters.

void lcd_SendCommand1(uint8_t cmd, uint8_t param)

Sends a command with one byte parameter.

void lcd_SendCommand2(uint8_t cmd, uint8_t param1, uint8_t param2)

Sends a command with two byte parameters.

void lcd_SendSizedCommandBytes(uint16_t sized_cmd, ...)

Sends a command with an arbitrary number of byte parameters.

You can also use the lcd_SendCommandBytes() convenience macro to specify the command and the number of parameters separately.

Parameters
  • sized_cmd[in] An LCD_SIZEDCMD literal, specifying number of bytes

  • ...[in] One function parameter for each byte parameter

void lcd_SendSizedCommandWords(uint16_t sized_cmd, ...)

Sends a command with an arbitrary number of 16-bit word parameters.

The parameters should be passed as their actual values, and are converted to big endian when transferred over SPI.

You can also use the lcd_SendCommandWords() convenience macro to specify the command and the number of parameters separately.

Parameters
  • sized_cmd[in] An LCD_SIZEDCMD literal, specifying number of words

  • ...[in] One function parameter for each word parameter

void lcd_SetUniformGamma(void)

Sets a gamma profile that provides a uniform perceived change in brightness as the color components change.

This fixes a flaw in TI’s default gamma profile that makes some darker colors indistinguishable.

void lcd_SetDefaultGamma(void)

Restores TI’s default gamma profile.