Stores list of low-level display commands. More...

#include <DisplayList.h>

Inheritance diagram for Graphics::DisplayList:
Collaboration diagram for Graphics::DisplayList:

Classes

struct  Entry
 Values returned from readEntry More...
 
union  Header
 Each list entry starts with a header. More...
 

Public Types

enum  Code : uint8_t { XX }
 
enum  CodeArgLengths : uint8_t { XX }
 Obtain maximum size for command, not including variable data which may be added. More...
 
using Callback = void(*)(void *parameterData)
 Queued callback. More...
 

Public Member Functions

 DisplayList (AddressWindow &addrWindow, size_t bufferSize)
 
 DisplayList (AddressWindow &addrWindow, const FSTR::ObjectBase &data)
 Create pre-defined display list from flash data. More...
 
 DisplayList (AddressWindow &addrWindow, const void *data, size_t length)
 Create initialised display list from RAM data. More...
 
void reset ()
 Reset the display list ready for re-use List MUST NOT be in use! More...
 
bool isEmpty () const
 Determine if any commands have been stored for execution. More...
 
uint16_t freeSpace () const
 Get number of bytes remaining in buffer. More...
 
uint16_t readOffset () const
 Get current read position. More...
 
uint16_t used () const
 Get number of bytes stored in buffer. More...
 
const uint8_tgetContent () const
 Get read-only pointer to start of buffer. More...
 
uint8_tgetBuffer (uint16_t &available)
 Get some space in the list to write pixel data. More...
 
uint8_tgetBuffer (uint16_t minBytes, uint16_t &available)
 Get some space in the list to write pixel data. More...
 
void commit (uint16_t length)
 Commit block of data to the list. More...
 
bool writeCommand (uint8_t command, uint32_t data, uint8_t length)
 Write command with 1-4 bytes of parameter data. More...
 
bool writeCommand (uint8_t command, const void *data, uint16_t length)
 Write command with variable amount of parameter data. More...
 
bool writeData (const void *data, uint16_t length)
 Add WRITE command plus data. More...
 
bool writeDataBuffer (SharedBuffer &data, size_t offset, uint16_t length)
 Add WRITE command plus external data. More...
 
bool blockFill (const void *data, uint16_t length, uint32_t repeat)
 Perform a block fill operation with repeat, e.g. multiple pixel fill or repeated pattern. More...
 
bool setAddrWindow (const Rect &rect)
 Set window for read/write operations. More...
 
bool setPixel (PackedColor color, uint8_t bytesPerPixel, Point pt)
 Set a single pixel. More...
 
bool readMem (void *buffer, uint16_t length)
 Read a block of display memory. More...
 
bool writeCallback (Callback callback, void *params, uint16_t paramLength)
 Request a callback. More...
 
bool fill (const Rect &rect, PackedColor color, uint8_t bytesPerPixel, FillInfo::Callback callback)
 Perform a block fill operation with blending. More...
 
bool canLockBuffer ()
 Enforce maximum number of locked buffers to conserve memory. More...
 
bool lockBuffer (SharedBuffer &buffer)
 Lock a shared buffer by storing a reference to it. This will be released when reset() is called. More...
 
bool require (uint16_t length)
 Check if list has space for the given number of bytes. More...
 
bool readEntry (Entry &info)
 Read next command list entry. More...
 
void prepare (Callback callback, void *param)
 Prepare for playback. More...
 

Static Public Member Functions

static String toString (Code code)
 

Protected Member Functions

void write (uint8_t c)
 Write a byte into the display list buffer. More...
 
void writeHeader (Code code, uint16_t length)
 Write a Header structure to the buffer. More...
 
void write16 (uint16_t c)
 Write a value as 2 bytes. More...
 
void write (const void *data, uint16_t length)
 Write a block of data into the display list buffer. More...
 
void writeVar (uint16_t count)
 Write a value using 1 or 2 bytes as required. More...
 
Code getWriteCode ()
 Get the appropriate command code to use for a write operation. More...
 
Code getReadCode ()
 Get the appropriate command code to use for a read operation. More...
 
void internalSetAddrWindow (const Rect &rect)
 
void read (void *data, uint16_t len)
 Read block of data from buffer. More...
 

Protected Attributes

Callback callback {nullptr}
 
void * param {nullptr}
 
std::unique_ptr< uint8_t[]> buffer
 
uint16_t size {0}
 Number of bytes stored in buffer. More...
 
uint16_t offset {0}
 Current read position. More...
 

Static Protected Attributes

static constexpr size_t maxLockedBuffers {8}
 

Detailed Description

Stores list of low-level display commands.

Used by hardware surfaces to efficiently buffer commands which are then executed in interrupt context.

The ILI9341 4-wire SPI mode is awkard to use so to allow more efficient access the command and data information is buffered as various types of 'chunk' using this class. A single HSPI request packet is used for all requests and is re-filled in interrupt context from this list.

Count values (data length) are stored as either 1 or 2 bytes. Values less than 0x80 bytes are stored in 1 byte, values from 0x0080 to 0x7fff are stored MSB first with the top bit set, followed by the LSB. For example, 0x1234 would be stored as 0x92 0x34.

Commands are stored in 1 byte. To allow use of this class with other displays may require adjusting this, perhaps converting this into a class template to accommodate these differences more efficiently.

  • Standard chunk. Contains a display-specific command byte followed by optional data.
    • command (1 byte)
    • data length (1 or 2 bytes)
    • data (variable length)
  • Data chunk (no command).
    • COMMAND_DATA (1 byte)
    • data length (1 or 2 bytes)
    • data (variable length)
  • Repeated data chunk (no command). Used to perform colour fills.
    • COMMAND_DATA_REPEAT (1 byte)
    • data length (1 or 2 bytes)
    • repeat count (1 or 2 bytes)
    • data (variable length)
  • Read command. Defines a single read command packet. Reading is particularly awkward on the ILI9341 as it 'forgets' the read position after each read packet. Reading a block of display memory therefore requires the address window to be set immediately before the RAMRD instruction. The final block in the sequence is a CALLBACK command.
    • COMMAND_READ (1 byte)
    • data length (1 or 2 bytes)
    • command (1 byte) The display-specific command to issue
    • buffer address (4 bytes)
  • Callback. Invokes a callback function (see Callback type). Note that the single parameter points to a copy of the original data which is stored in the list.
    • COMMAND_CALLBACK (1 byte)
    • parameter data length (1 or 2 bytes)
    • callback function pointer (4 bytes)
    • callback parameters (variable)

Member Typedef Documentation

◆ Callback

using Graphics::DisplayList::Callback = void (*)(void* parameterData)

Queued callback.

Parameters
parameterDataA copy of the original parameter data

The parameter data is copied so the caller does not need to allocate memory dynamically. The data must start on a 32-bit word boundary.

Member Enumeration Documentation

◆ Code

Enumerator
XX 

◆ CodeArgLengths

Obtain maximum size for command, not including variable data which may be added.

Used to check space before starting a command sequence. Actual space used may be less than this.

Enumerator
XX 

Constructor & Destructor Documentation

◆ DisplayList() [1/3]

Graphics::DisplayList::DisplayList ( AddressWindow addrWindow,
size_t  bufferSize 
)
inline
Parameters
commandsCodes corresponding to specific display commands
addrWindowReference to current device address window, synced between lists
bufferSize

◆ DisplayList() [2/3]

Graphics::DisplayList::DisplayList ( AddressWindow addrWindow,
const FSTR::ObjectBase data 
)
inline

Create pre-defined display list from flash data.

Used for initialisation data

◆ DisplayList() [3/3]

Graphics::DisplayList::DisplayList ( AddressWindow addrWindow,
const void *  data,
size_t  length 
)
inline

Create initialised display list from RAM data.

Used for initialisation data

Member Function Documentation

◆ blockFill()

bool Graphics::DisplayList::blockFill ( const void *  data,
uint16_t  length,
uint32_t  repeat 
)

Perform a block fill operation with repeat, e.g. multiple pixel fill or repeated pattern.

◆ canLockBuffer()

bool Graphics::DisplayList::canLockBuffer ( )
inline

Enforce maximum number of locked buffers to conserve memory.

Return values
booltrue if call to lockBuffer() will succeed

◆ commit()

void Graphics::DisplayList::commit ( uint16_t  length)

Commit block of data to the list.

Parameters
lengthHow many bytes have been written
Note
MUST NOT call with more data than returned from available in getBuffer call.

◆ fill()

bool Graphics::DisplayList::fill ( const Rect rect,
PackedColor  color,
uint8_t  bytesPerPixel,
FillInfo::Callback  callback 
)

Perform a block fill operation with blending.

Parameters
rectArea to fill
color
bytesPerPixel
callbackInvoked in interrupt context to perform blend operation

Performs a read/blend/write operation. Use to perform transparent fills or other blend operations on small regions of display memory.

◆ freeSpace()

uint16_t Graphics::DisplayList::freeSpace ( ) const
inline

Get number of bytes remaining in buffer.

◆ getBuffer() [1/2]

uint8_t* Graphics::DisplayList::getBuffer ( uint16_t available)

Get some space in the list to write pixel data.

Parameters
available(OUT) How much space is available
Return values
uint8_t*Where to write data

Call commit after the data has been written

◆ getBuffer() [2/2]

uint8_t* Graphics::DisplayList::getBuffer ( uint16_t  minBytes,
uint16_t available 
)
inline

Get some space in the list to write pixel data.

Parameters
minBytesMinimum bytes required
available(OUT) How much space is available
Return values
uint8_t*Where to write data, nullptr if required space not available

Call commit after the data has been written

◆ getContent()

const uint8_t* Graphics::DisplayList::getContent ( ) const
inline

Get read-only pointer to start of buffer.

◆ getReadCode()

Code Graphics::DisplayList::getReadCode ( )
inlineprotected

Get the appropriate command code to use for a read operation.

Code depends on whether this is the first read packet or not

◆ getWriteCode()

Code Graphics::DisplayList::getWriteCode ( )
inlineprotected

Get the appropriate command code to use for a write operation.

Code depends on whether this is the first write packet or not

◆ internalSetAddrWindow()

void Graphics::DisplayList::internalSetAddrWindow ( const Rect rect)
protected

◆ isEmpty()

bool Graphics::DisplayList::isEmpty ( ) const
inline

Determine if any commands have been stored for execution.

◆ lockBuffer()

bool Graphics::DisplayList::lockBuffer ( SharedBuffer buffer)

Lock a shared buffer by storing a reference to it. This will be released when reset() is called.

◆ prepare()

void Graphics::DisplayList::prepare ( Callback  callback,
void *  param 
)
inline

Prepare for playback.

Parameters
callbackInvoked when playback has completed, in task context
paramParameter passed to callback

◆ read()

void Graphics::DisplayList::read ( void *  data,
uint16_t  len 
)
inlineprotected

Read block of data from buffer.

Called during playback in interrupt context

◆ readEntry()

bool Graphics::DisplayList::readEntry ( Entry info)

Read next command list entry.

Parameters
info
Return values
boolfalse if there are no more commands

Used by virtual display and for debugging. SpiDisplayList uses a different mechanism for reading.

◆ readMem()

bool Graphics::DisplayList::readMem ( void *  buffer,
uint16_t  length 
)

Read a block of display memory.

◆ readOffset()

uint16_t Graphics::DisplayList::readOffset ( ) const
inline

Get current read position.

◆ require()

bool Graphics::DisplayList::require ( uint16_t  length)
inline

Check if list has space for the given number of bytes.

Return values
booltrue if there's room

◆ reset()

void Graphics::DisplayList::reset ( )

Reset the display list ready for re-use List MUST NOT be in use!

◆ setAddrWindow()

bool Graphics::DisplayList::setAddrWindow ( const Rect rect)

Set window for read/write operations.

◆ setPixel()

bool Graphics::DisplayList::setPixel ( PackedColor  color,
uint8_t  bytesPerPixel,
Point  pt 
)

Set a single pixel.

◆ toString()

static String Graphics::DisplayList::toString ( Code  code)
static

◆ used()

uint16_t Graphics::DisplayList::used ( ) const
inline

Get number of bytes stored in buffer.

◆ write() [1/2]

void Graphics::DisplayList::write ( const void *  data,
uint16_t  length 
)
inlineprotected

Write a block of data into the display list buffer.

◆ write() [2/2]

void Graphics::DisplayList::write ( uint8_t  c)
inlineprotected

Write a byte into the display list buffer.

◆ write16()

void Graphics::DisplayList::write16 ( uint16_t  c)
inlineprotected

Write a value as 2 bytes.

◆ writeCallback()

bool Graphics::DisplayList::writeCallback ( Callback  callback,
void *  params,
uint16_t  paramLength 
)

Request a callback.

Parameters
callbackCallback function to invoke
paramsParameter data, will be stored in list
paramLengthSize of parameter data

The callback will be invoked (in interrupt context) when read from the display list

◆ writeCommand() [1/2]

bool Graphics::DisplayList::writeCommand ( uint8_t  command,
const void *  data,
uint16_t  length 
)

Write command with variable amount of parameter data.

◆ writeCommand() [2/2]

bool Graphics::DisplayList::writeCommand ( uint8_t  command,
uint32_t  data,
uint8_t  length 
)
inline

Write command with 1-4 bytes of parameter data.

◆ writeData()

bool Graphics::DisplayList::writeData ( const void *  data,
uint16_t  length 
)

Add WRITE command plus data.

◆ writeDataBuffer()

bool Graphics::DisplayList::writeDataBuffer ( SharedBuffer data,
size_t  offset,
uint16_t  length 
)

Add WRITE command plus external data.

Parameters
dataWill be locked until display list has been executed

◆ writeHeader()

void Graphics::DisplayList::writeHeader ( Code  code,
uint16_t  length 
)
inlineprotected

Write a Header structure to the buffer.

Parameters
codeCommand code to store
lengthLength to store in header

◆ writeVar()

void Graphics::DisplayList::writeVar ( uint16_t  count)
inlineprotected

Write a value using 1 or 2 bytes as required.

Member Data Documentation

◆ buffer

std::unique_ptr<uint8_t[]> Graphics::DisplayList::buffer
protected

◆ callback

Callback Graphics::DisplayList::callback {nullptr}
protected

◆ maxLockedBuffers

constexpr size_t Graphics::DisplayList::maxLockedBuffers {8}
staticconstexprprotected

◆ offset

uint16_t Graphics::DisplayList::offset {0}
protected

Current read position.

◆ param

void* Graphics::DisplayList::param {nullptr}
protected

◆ size

uint16_t Graphics::DisplayList::size {0}
protected

Number of bytes stored in buffer.


The documentation for this class was generated from the following file: