-
Notifications
You must be signed in to change notification settings - Fork 317
devicedesign
This wiki page explains the device structure. It should contain enough information to enable users to create their own device.
I will start working on this wiki page and it might be incomplete for a (long?) time. Please excause...
The U8glib device is a C structure:
struct _u8g_dev_t
{
u8g_dev_fnptr dev_fn; /* device procedure */
void *dev_mem; /* device memory */
u8g_com_fnptr com_fn; /* communication procedure */
};
typedef struct _u8g_dev_t u8g_dev_t;
There are three parts in a device structure:
-
dev_fn
(required): A callback procedure, which handles messages from the graphics procedures. -
dev_mem
(optional): A pointer to some local memory. -
com_fn
(optional): A communication procedure
Basic idea is, that (parts of) the frame buffer is stored via dev_mem
. Display specific procedures (display init, pixel set and clear) are handled by dev_fn
and communication specific details (TWI, SPI, etc) could be handled via com_fn
.
It is always possible that dev_fn
directly writes to the display device. In this case set com_fn
to u8g_com_null_fn
.
Here is a template for a very simple device:
uint8_t my_dev_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
/* handle messages here */
return 1; /* successful handled */
}
u8g_dev_t u8g_dev_my_simple_display = { my_dev_fn, NULL, u8g_com_null_fn };
All the communication between the graphics procedures and the device callback procedure (dev_fn
) is done via messages. A message is a number, which is passed in the argument msg
of the dev_fn
:
uint8_t my_dev_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
In some cases, there are additional arguments and parameters together with msg
. In this case arg
is a none-NULL pointer to these additional arguments.
A typical device callback will look like this:
uint8_t my_dev_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
switch(msg)
{
case U8G_DEV_MSG_INIT:
/* setup/init display */
/* ... */
break;
case U8G_DEV_MSG_PAGE_NEXT:
/* write a page to the display */
/* ... */
break;
/* maybe handle more messages */
}
/* make a call to a suitable page buffer procedure */
return u8g_dev_pb8v1_base_fn(u8g, dev, msg, arg);
}
This is a small reference of all messages:
-
U8G_DEV_MSG_INIT
: Setup and init display, no args. -
U8G_DEV_MSG_STOP
: Shutdown display, no args (not used at the moment). -
U8G_DEV_MSG_CONTRAST
: Set contrast or bightness of the display,arg
is a pointer touint8_t
which contains the contrast value (0..255). -
U8G_DEV_MSG_SLEEP_ON
: Display should enter sleep mode, no args. -
U8G_DEV_MSG_SLEEP_OFF
: Display should recover from sleep mode, no args. -
U8G_DEV_MSG_PAGE_FIRST
: Picture loop will start now. Page buffer procedures will reset the page handling to the first page and clear the buffer. -
U8G_DEV_MSG_PAGE_NEXT
: A page has been finished,dev_fn
should transfer page to the device, page buffer procedures will setup next page. 0 should be returned if there are no further pages required. There are no args for this message. -
U8G_DEV_MSG_GET_PAGE_BOX
: Return dimensions of the page.arg
is a pointer tou8g_dev_arg_bbx_t
. This messages is handled by page buffer procedures. -
U8G_DEV_MSG_SET_PIXEL
: Set a pixel.arg
is a pointer tou8g_dev_arg_pixel_t
. This messages is handled by page buffer procedures. -
U8G_DEV_MSG_SET_8PIXEL
: Set a sequence of 8 pixel.arg
is a pointer tou8g_dev_arg_pixel_t
. This messages is handled by page buffer procedures. -
U8G_DEV_MSG_SET_COLOR_INDEX
(until v1.12): Not used -
U8G_DEV_MSG_SET_COLOR_ENTRY
(since v1.13): Set color palette entry.arg
is a pointer tou8g_dev_arg_irgb_t
. -
U8G_DEV_MSG_SET_XY_CB
: Not used -
U8G_DEV_MSG_GET_WIDTH
: Return the width of the display.arg
is a pointer tou8g_uint_t
. The width must be stored at the address pointed to byarg
. -
U8G_DEV_MSG_GET_HEIGHT
: Return the height of the display.arg
is a pointer tou8g_uint_t
. The height must be stored at the address pointed to byarg
. -
U8G_DEV_MSG_GET_MODE
: Return the display mode as return value ofdev_fn
, no other args. Possible return values areU8G_MODE_BW
andU8G_MODE_GRAY2BIT
(device for stdout)