Difference between revisions of "GDISP"

Revision as of 13:22, 5 July 2014

The GDISP module provides a simple interface for graphic displays and a feature rich set of highlevel functions to draw primitive shapes such as lines, circles and rectangles, but also font rendering, clipping and other advanced features.

Whilst most other graphics libraries require the use of a framebuffer, GDISP does not necessarily need one. This allows to drive graphics displays on microcontrollers and other low-performance systems that have insufficient RAM for a frame buffer.

Some LCD controllers offer hardware accelerated drawings for complex drawing operations such as circles or ellipses. The GDISP module is based on a software emulation layer: When the LCD controller does not support these features (most cases), the GDISP module emulates these drawing operations. Therefore, the exact same application code can be used on very different hardware platforms.

Furthermore, you can drive more than just one display with GDISP. They don't even need to have the same display driver. Please refer to the multiple displays section for more information. Especially interesting might be the use of one or more remote displays.

API reference

The API reference of the GDISP module can be found here.

Board file

The board file API for the GDISP module looks like the following:

static void     init_board(GDisplay *g);
static void     post_init_board(GDisplay *g);
static void     setpin_reset(GDisplay *g, bool_t state);
static void     set_backlight(GDisplay *g, uint8_t percent);
static void     acquire_bus(GDisplay *g);
static void     release_bus(GDisplay *g);
static void     write_index(GDisplay *g, uint16_t index);
static void     write_data(GDisplay *g, uint16_t data);
static void     setreadmode(GDisplay *g);
static void     setwritemode(GDisplay *g);
static uint16_t read_data(GDisplay *g);

For more information about the, see GDisplay.
Examples and a template file can be found under /drivers/gdisp/xxx/.

post_init_board()

The post_init_board() routine is usually used to increase the bus speed after successful initialization.

Controlls

It's possible to modify panel parameters such as the orientation, backlight or contrast through highlevel API. But before you can use any of the following features, you have to enable the GDISP_NEED_CONTROLL macro in your gfxconf.h first:

#define GDISP_NEED_CONTROL TRUE

Please note that all these features are optional. Not every GDISP driver may have all of the features listed below. Calling any of these calls when the driver or the controller does not support them is still safe - just nothing will happen.

Rotate your screen

You can change the orientation of your screen in 90 degree steps. This way, you cannot only use it in portrait or landscape mode, but also in inverted portrait and inverted landscape mode:

gdispSetOrientation(GDISP_ROTATE_0);    // default orientation
gdispSetOrientation(GDISP_ROTATE_90);   // flip by 90 degrees
gdispSetOrientation(GDISP_ROTATE_180);  // flip by 180 degrees
gdispSetOrientation(GDISP_ROTATE_270);  // flip by 270 degrees

In case of you're using the calibration routine of the GINPUT module, you must keep the screen in the default orientation until the calibration has been completed. Furthermore, the default panel orientation can be set in the configuration file.

Power control

Most LCD controllers allow it to change the power level of your LCD.

gdispSetPowerMode(powerOff);
gdispSetPowerMode(powerOn);
gdispSetPowerMode(powerSleep);

You can wake up the display after entering the sleep mode by calling gdispSetPowerMode(powerOn).

Backlight and Contrast

GDISP provides an interface to set the backlight brightness and the contrast of your LCD module in a percentage.

gdispSetBacklight(50);  // set backlight to 50%
gdispSetContrast(50);   // set contrast to 50%

Panel Parameters

There are a few functions which return different LCD panel paremeters such as the width and the height in pixels which make it easy to write code which works on different display resolutions.

gdispGetWdith();      // returns the width or the lcd panel in pixels
gdispGetHeight();     // returns the height of the lcd panel in pixels
gdispGetBacklight();  // returns the percent of the backlight
gdispGetContrast();   // returns the percent of the contrast

Color format

ToDo.

Drawing

The GDISP module provides many API calls to draw to a display. See Drawing.

Font rendering

The GDISP module provides a font rendering engine with features like unicode support, kerning, anti-aliasing and more. See Font rendering.

Images

The GDISP module provides built-in decoders for a variety of image formats. See Images.

FrameBuffer

It is possible to use a framebuffer using the framebuffer driver. The framebuffer driver is usually used in systems like the STM32F4x9 microcontroller that have a built-in display driver but that require an external framebuffer (SDRAM).

The board file template of the framebuffer driver shows how to initialize the framebuffer struct.

static void board_init(GDisplay *g, fbInfo *fbi) {
	// TODO: Initialize your frame buffer device here
 
	// TODO: Set the details of the frame buffer
	g->g.Width = 640;
	g->g.Height = 480;
	g->g.Backlight = 100;
	g->g.Contrast = 50;
	fbi->linelen = g->g.Width * sizeof(LLDCOLOR_TYPE);		// bytes per row
	fbi->pixels = 0;						// pointer to the memory frame buffer
}

Hardware acceleration

ToDo

Multipel displays

The GDISP module can drive more than just one display. See Multiple displays.

Remote displays

The GDISP module can drive remote displays. See Remote displays.

GDisplay

ToDo

struct GDisplay {
	// The public GDISP stuff - must be the first element
	GDISPControl				g;
 
	#if GDISP_TOTAL_CONTROLLERS > 1
		const struct GDISPVMT const *	vmt;		// The Virtual Method Table
	#endif
 
	void *						priv;				// A private area just for the drivers use.
	void *						board;				// A private area just for the board interfaces use.
 
	uint8_t						systemdisplay;
	uint8_t						controllerdisplay;
	uint16_t					flags;
		#define GDISP_FLG_INSTREAM		0x0001		// We are in a user based stream operation
		#define GDISP_FLG_SCRSTREAM		0x0002		// The stream area currently covers the whole screen
		#define GDISP_FLG_DRIVER		0x0004		// This flags and above are for use by the driver
 
	// Multithread Mutex
	#if GDISP_NEED_MULTITHREAD
		gfxMutex				mutex;
	#endif
 
	// Software clipping
	#if GDISP_HARDWARE_CLIP != TRUE && (GDISP_NEED_CLIP || GDISP_NEED_VALIDATION)
		coord_t					clipx0, clipy0;
		coord_t					clipx1, clipy1;		/* not inclusive */
	#endif
 
	// Driver call parameters
	struct {
		coord_t			x, y;
		coord_t			cx, cy;
		coord_t			x1, y1;
		coord_t			x2, y2;
		color_t			color;
		void			*ptr;
	} p;
 
	// In call working buffers
 
	#if GDISP_NEED_TEXT
		// Text rendering parameters
		struct {
			font_t		font;
			color_t		color;
			color_t		bgcolor;
			coord_t		clipx0, clipy0;
			coord_t		clipx1, clipy1;
		} t;
	#endif
	#if GDISP_LINEBUF_SIZE != 0 && ((GDISP_NEED_SCROLL && !GDISP_HARDWARE_SCROLL) || (!GDISP_HARDWARE_STREAM_WRITE && GDISP_HARDWARE_BITFILLS))
		// A pixel line buffer
		color_t		linebuf[GDISP_LINEBUF_SIZE];
	#endif
 
};