4 Display Driver Adaptation

The lowest level of the graphics library stack is the display driver. Although the display driver API is specified by the graphics library, the source is specific to the board and display hardware and can be found in the C:\ti\TivaWare_C_Series-2.2.0.295\examples\boards\<board>\drivers directory. The driver source file name is typically derived from the display manufacturer, supported display controller part, display resolution, and bit depth. For example, the display driver for the dk-tm4c129x is named Kentec320x240x16_ssd2119.c since it supports a Kentec display using an SSD2119 controller and offers 320 x 240 resolution at 16 bits per pixel. The display driver for the SPI-based BOOSTXL-K350QVG-SI BoosterPack to be used on the EK-TM4C1294XL LaunchPad is named Kentec320x240x16_ssd2119_spi.c.

The display driver’s responsibility is to translate calls made to the standard display driver API into orders to draw pixels or lines on the display. The interface to the driver is intended to offer the absolute minimum subset of drawing orders required to support the main graphics library and, as a result, make it extremely straightforward to develop a driver for a new display very quickly.

The display driver API includes the following basic functions that must be supported by every display driver:

static void
PixelDraw(void *pvDisplayData, int32_t i32X,
                               int32_t i32Y, uint32_t ui32Value)

static void
PixelDrawMultiple(void *pvDisplayData, int32_t i32X,
                                       int32_t i32Y, int32_t i32X0,
                                       int32_t i32Count, int32_t i32BPP,
                                       const uint8_t *pui8Data,
                                       const uint8_t *pui8Palette)

static void
LineDrawH(void *pvDisplayData, int32_t i32X1,
                               int32_t i32X2, int32_t i32Y,
                               uint32_t ui32Value)

static void
LineDrawV(void *pvDisplayData, int32_t i32X,
                               int32_t i32Y1, int32_t i32Y2,
                               uint32_t ui32Value)

static void
RectFill(void *pvDisplayData, const tRectangle *psRect,
                              uint32_t ui32Value)

static uint32_t
ColorTranslate(void *pvDisplayData, uint32_t ui32Value)

static void
2119Flush(void *pvDisplayData)

The actual names of these functions are not important since they are provided to the graphics library by means of a function pointer table. This can be found in the tDisplay structure that the display driver exports and that the applications uses when calling the graphics API function.

const tDisplay g_sKentec320x240x16_SSD2119 =
{
    sizeof(tDisplay),
#if defined(PORTRAIT) || defined(PORTRAIT_FLIP)
    240,
    320,
#else
    320,
    240,
#endif
    Kentec320x240x16_SSD2119PixelDraw,
    Kentec320x240x16_SSD2119PixelDrawMultiple,
    Kentec320x240x16_SSD2119LineDrawH,
    Kentec320x240x16_SSD2119LineDrawV,
    Kentec320x240x16_SSD2119RectFill,
    Kentec320x240x16_SSD2119ColorTranslate,
    Kentec320x240x16_SSD2119Flush
};

Additionally, the display driver typically provides an initialization function (Kentec320x240x16_SSD2119Init()) that the application is expected to call prior to initializing the graphics library. This call is used to initialize the underlying graphics hardware and clear the screen.

Notice that the driver API contains significantly fewer graphics primitives than the low-level graphics API. Most graphics primitives are broken down by the higher-level code and passed to the driver in pieces. For example, an unfilled rectangle is drawn using two calls to the LineDrawV function and two calls to the LineDrawH function. Similarly, text is rendered using multiple calls to the PixelDraw and LineDrawH functions. This model works well with small, low-cost displays which do not typically include any graphics acceleration hardware but do often include the ability to choose drawing direction and copy lines of pixels.

The other higher-level feature carried out by the low-level graphics layer on behalf of the display driver is clipping. No coordinates that are outside the bounds of the display are ever passed to the display driver since this is checked for and handled in the layer above. Using this approach, it becomes quick and easy to produce a new graphics driver since only a small number of simple functions need to be developed.