Macros
#define	SERDISP_VERSION_MAJOR
	major version of serdisplib

#define	SERDISP_VERSION_MINOR
	minor version of serdisplib

#define	SERDISP_VERSION_EXTRA
	extra version postfix (ignored)

#define	SERDISP_VERSION(_major, _minor)
	calculates a serdisplib version code returns the version code which is calculated using major and minor version information More...

#define	SERDISP_VERSION_GET_MAJOR(_code)

#define	SERDISP_VERSION_GET_MINOR(_code)

Device handling functions
serdisp_t *	serdisp_init (serdisp_CONN_t *, const char dispname[], const char optionstring[])
	initialises a display More...

void	serdisp_close (serdisp_t *dd)
	closes display without erasing it More...

void	serdisp_quit (serdisp_t *dd)
	closes display More...

int	serdisp_reset (serdisp_t *dd)
	re-initialises the display More...

serdisp_t *	serdisp_fullreset (serdisp_t *dd)
	resets the display More...

serdisp_CONN_t *	serdisp_getSDCONN (serdisp_t *dd)
	gets serdisp connect descriptor More...

const char *	serdisp_defaultdevice (const char *dispname)
	get default device expression More...

Library version
long	serdisp_getversioncode (void)
	gets version code More...

Drawing functions
void	serdisp_setsdpixel (serdisp_t *dd, int x, int y, SDCol sdcol)
	changes a pixel in the display buffer More...

SDCol	serdisp_getsdpixel (serdisp_t *dd, int x, int y)
	gets pixel at position (x/y) More...

void	serdisp_clearbuffer (serdisp_t *dd)
	resets the display buffer More...

void	serdisp_clear (serdisp_t *dd)
	clears whole display More...

void	serdisp_rewrite (serdisp_t *dd)
	rewrites whole display More...

void	serdisp_update (serdisp_t *dd)
	updates whole display More...

void	serdisp_blink (serdisp_t *dd, int what, int cnt, int delta)
	flashes the display or the background light More...

Get/Set display settings and informations
int	serdisp_getwidth (serdisp_t *dd)
	gets width of display More...

int	serdisp_getheight (serdisp_t *dd)
	gets height of display More...

int	serdisp_getcolours (serdisp_t *dd)
	gets amount of colours More...

int	serdisp_getdepth (serdisp_t *dd)
	gets colour depth More...

int	serdisp_getpixelaspect (serdisp_t *dd)
	gets pixel aspect ratio More...

const char *	serdisp_getdisplayname (serdisp_t *dd)
	gets unprocessed display name More...

void	serdisp_currdisplaydescription (serdisp_t dd, serdisp_display_t displaydesc)
	gets display description for the display given by a device descriptor More...

int	serdisp_nextdisplaydescription (serdisp_display_t *displaydesc)
	iterates through supported displays More...

int	serdisp_isdisplay (const char *displayname)
	tests if display is supported More...

int	serdisp_getdisplaydescription (const char displayname, serdisp_display_t displaydesc)
	gets description to a display More...

int	serdisp_nextwiringdescription (const char displayname, serdisp_wiredef_t wiredesc)
	iterates through wiring descriptions for a display More...

Display options
void	serdisp_setoption (serdisp_t dd, const char optionname, long value)
	changes a display option More...

long	serdisp_getoption (serdisp_t dd, const char optionname, int *typesize)
	gets the value of a display option More...

int	serdisp_isoption (serdisp_t dd, const char optionname)
	tests if option is supported More...

int	serdisp_getoptiondescription (serdisp_t dd, const char optionname, serdisp_options_t *optiondesc)
	gets a description to a given option More...

int	serdisp_nextoptiondescription (serdisp_t dd, serdisp_options_t optiondesc)
	gets the next option description More...

int	serdisp_nextstaticoptiondesc (const char displayname, serdisp_options_t optiondesc)
	gets the next option description More...

Backward Compatibility functions
void	serdisp_setpixel (serdisp_t *dd, int x, int y, long colour)
	changes a pixel in the display buffer More...

long	serdisp_getpixel (serdisp_t *dd, int x, int y)
	gets pixel at position (x/y) More...

Deprecated functions
void	serdisp_feature (serdisp_t *dd, int feature, int value)
	changes a display feature More...

void	serdisp_setpixels (serdisp_t dd, int x, int y, int w, int h, byte data)
	changes an area in the display buffer More...

Detailed Description

Introduction

All elementary functions for controlling a display are defined here (except serdisp_setcolour() and serdisp_getcolour()).

Attention: Only these functions should be used.

No descriptor fields or internal functions should be accessed directly as these are subject to change.

Macro Definition Documentation

#define SERDISP_VERSION	(	_major,
		_minor
	)

Parameters

_major	major version
_minor	minor version

Example:
/* only include code if the header files for serdisplib are at least of version 1.95 */ #if (SERDISP_VERSION_CODE >= SERDISP_VERSION(1,95)) ... #endif

#define SERDISP_VERSION_GET_MAJOR ( _code )

returns the major version information out of a serdisplib version code

Parameters

_code serdisplib version code

#define SERDISP_VERSION_GET_MINOR ( _code )

returns the minor version information out of a serdisplib version code

Parameters

_code serdisplib version code

Function Documentation

void serdisp_blink	(	serdisp_t *	dd,
		int	what,
		int	cnt,
		int	delta
	)

blinks/flashes either the display or the background light

Parameters

dd	device descriptor
what	0: flashes backlight, 1: blinks display by inverting the display
cnt	how often should there be blinking
delta	delay between two blinking intervals

void serdisp_clear ( serdisp_t * dd )

Parameters

dd	device descriptor

void serdisp_clearbuffer ( serdisp_t * dd )

resets the internal display buffer

Parameters

dd	device descriptor

Attention: display will not be redrawn!
serdisp_clear() clears and redraws the display.

void serdisp_close ( serdisp_t * dd )

close display but without erasing its content and without switching it off. the output device remains opened.

this function may for example be used for programs that want to output something and than exit, but without clearing the display (for this, SDCONN_close() shouldn't be called either)

Parameters

dd	device descriptor

Attention: this will NOT work as expected with serial port and ioctl (TxD will be set to low in any case -> so display will be w/o power) so the only solution would be a separate power supply when using ioctl.

this seems to be an operating system specific behaviour and cannot be influenced

but: directIO works as expected (TxD will NOT be reset after program exit)

void serdisp_currdisplaydescription	(	serdisp_t *	dd,
		serdisp_display_t *	displaydesc
	)

Parameters

[in]	dd	device descriptor
[out]	displaydesc	address of display descriptor

Example:

 serdisp_display_t displaydesc;
 
 serdisp_currdisplaydescription(dd, &displaydesc)) {
 printf("description of active display: %s\n", displaydesc.description);

Since: 1.96

const char* serdisp_defaultdevice ( const char * dispname )

gets default device expression for given display name

Parameters

dispname display name

Returns: default device expression or "" if not found or defined

Since: 2.00

void serdisp_feature	(	serdisp_t *	dd,
		int	feature,
		int	value
	)

Parameters

dd	device descriptor
feature	feature to change: FEATURE_CONTRAST .. change display contrast (value: 0-MAX_CONTRAST) FEATURE_BACKLIGHT .. 0: off, 1: on, 2: toggle FEATURE_INVERT .. 0: normal display, 1: inverted display, 2: toggle FEATURE_ROTATE .. 0: normal, 1 or 180: bottom-up, 90: 90 degrees, 270: 270 degrees
value	value for option (see above)

Deprecated:: superseded by serdisp_setoption()

serdisp_t* serdisp_fullreset ( serdisp_t * dd )

resets the display (clears runtime_error flag, closes and reopens device, re-inits display)

Parameters

dd	device descriptor

Return values

!NULL	device descriptor
NULL	unsucessful reset

int serdisp_getcolours ( serdisp_t * dd )

get amount of colours supported by the configuration currently used

Parameters

dd	device descriptor

Returns: amount of supported colours

int serdisp_getdepth ( serdisp_t * dd )

get colour depth supported by the configuration currently used

Parameters

dd	device descriptor

Returns: colour depth

Since: 1.95

int serdisp_getdisplaydescription	(	const char *	displayname,
		serdisp_display_t *	displaydesc
	)

Parameters

[in]	displayname	display/device name
[out]	displaydesc	address of display descriptor

Return values

1	display available
0	display unknown / unsupported

Example:

 serdisp_display_t displaydesc;
 displayname = "lph7366";
 
 int rc = serdisp_getdisplaydescription(displayname, &displaydesc);
 
 if (rc)
   printf("description for display %s: %s\n", displayname, displaydesc.description);

Since: 1.96

const char* serdisp_getdisplayname ( serdisp_t * dd )

gets the display name (unprocessed, spelling as it was used for serdisp_init())

Parameters

dd	device descriptor

Returns: display name

Since: 1.96

int serdisp_getheight ( serdisp_t * dd )

Parameters

dd	device descriptor

Returns: height of display

long serdisp_getoption	(	serdisp_t *	dd,
		const char *	optionname,
		int *	typesize
	)

change a display option (old: 'feature') (new, preferred version)

usually this function is only used for returning numeric values

using the following string hack strings may also be returned:
if typesize is requested and filled with size == 0 then the option is of type 'string'
its address is returned as 'long' and has to be re-casted like so:

 int typesize;
 long retval = serdisp_getoption(dd, "name", &typesize);
 if (typesize == 0)
   char* str = (char*) retval;

Parameters

[in]	dd	device descriptor
[in]	optionname	name of option
[out]	typesize	pointer to value containing size of option's type (in byte) (or, if 0 is passed here, this will be ignored)

Return values

<>-1	value of display option
-1	option is unknown

Since: 1.96

int serdisp_getoptiondescription	(	serdisp_t *	dd,
		const char *	optionname,
		serdisp_options_t *	optiondesc
	)

Parameters

[in]	dd	device descriptor
[in]	optionname	name of option (name or aliasname)
[out]	optiondesc	address of option descriptor

Return values

1	option is available
0	option unknown/unsupported

Since: 1.96

long serdisp_getpixel	(	serdisp_t *	dd,
		int	x,
		int	y
	)

gets hardware dependend colour information at position (x/y)

Parameters

dd	device descriptor
x	x-position
y	y-position

Returns: hardware dependent colour information at (x/y)

Attention: this function is hardware dependent!
for getting the hardware independent colour information serdisp_getsdcol() should be used.

Deprecated:: The byte size of colour is architecture dependent.
Architecture independent function serdisp_getsdpixel() should be used instead.

int serdisp_getpixelaspect ( serdisp_t * dd )

get pixel aspect ratio in percent (to avoid floating-point values)

pixels are quadratic: 100 will be returned
pixel width is twice pixel height: 200 will be returned
pixel width is half of pixel height: 50 will be returned

formula:

           w * ph       w, h: amount of pixels
 f = 100 * ------     pw, ph: display area (in micrometres, but unit has no influence on the calc.)
           h * pw          f: pixel aspect ratio in percent

Parameters

dd	device descriptor

Returns: pixel ascpect ratio in percent

Since: 1.95

serdisp_CONN_t* serdisp_getSDCONN ( serdisp_t * dd )

get serdisp connect descriptor used by the display

Parameters

dd	device descriptor

Returns: serdisp connect descriptor (output device)

SDCol serdisp_getsdpixel	(	serdisp_t *	dd,
		int	x,
		int	y
	)

gets hardware dependend colour information at position (x/y)

Parameters

dd	device descriptor
x	x-position
y	y-position

Returns: hardware dependent colour information at (x/y)

Attention: this function is hardware dependent!
for getting the hardware independent colour information serdisp_getsdcol() should be used.

Since: 1.98.0

long serdisp_getversioncode ( void )

Returns: version code of serdisp library

Since: 1.98

int serdisp_getwidth ( serdisp_t * dd )

Parameters

dd	device descriptor

Returns: width of display

serdisp_t* serdisp_init	(	serdisp_CONN_t *	sdcd,
		const char	dispname[],
		const char	optionstring[]
	)

Parameters

sdcd	output device handle
dispname	display name
optionstring	option string (extra options eg. from outside)

Return values

!NULL	device descriptor
NULL	unsuccuessful initialisation

Example:

1 serdisp_t* dd;

2 dd = serdisp_init(sdcd, "PCD8544", "WIRING=1;INVERT=YES");

int serdisp_isdisplay ( const char * displayname )

Parameters

displayname name or alias name of display to test

Return values

1	display is supported
0	display is unsupported

Since: 1.96

int serdisp_isoption	(	serdisp_t *	dd,
		const char *	optionname
	)

Parameters

dd	device descriptor
optionname	name of option to test

Return values

1	option is supported and read/writeable
-1	option is supported but read-only
0	option is not supported

Since: 1.96

int serdisp_nextdisplaydescription ( serdisp_display_t * displaydesc )

iterates through supported displays
the iteration is started with assigning an empty string to optiondesc.dispname

Parameters

[out] displaydesc address of display descriptor

Return values

1	successful
0	unsuccessful (no more supported diplays have been found)

Example:

(prints all supported displays (main display name and alias names))

 serdisp_display_t displaydesc;
 displaydesc.dispname = "";
 
 while(serdisp_nextdisplaydescription(&displaydesc)) {
   printf("name: %s   aliases: %s\n", displaydesc.dispname, displaydesc.aliasnames);
 }

Since: 1.96

int serdisp_nextoptiondescription	(	serdisp_t *	dd,
		serdisp_options_t *	optiondesc
	)

get the next option description (iterates through the options supported by the display)

initialise optiondesc with optiondesc.name = "" to start the iteration

eg:

 serdisp_options_t optiondesc;
 optiondesc.name = "";
 
 while(serdisp_nextoptiondescription(dd, &optiondesc)) {
   printf("%s\n", optiondesc.name);
 }

Parameters

[in]	dd	device descriptor
[out]	optiondesc	address of option descriptor

Return values

1	successful
0	unsuccessful (no more option has been found)

Since: 1.96

int serdisp_nextstaticoptiondesc	(	const char *	displayname,
		serdisp_options_t *	optiondesc
	)

get the next option description (iterates through the options supported by the display given by dispname)
this is the static version of serdisp_nextoptiondescription()

initialise optiondesc with optiondesc.name = "" to start the iteration

eg:

 serdisp_options_t optiondesc;
 optiondesc.name = "";
 
 while(serdisp_nextstaticoptiondesc("PCD8544", &optiondesc)) {
   printf("%s\n", optiondesc.name);
 }

Parameters

[in]	displayname	display/device name
[out]	optiondesc	address of option descriptor

Return values

1	successful
0	unsuccessful (no more option has been found)

Since: 1.98

int serdisp_nextwiringdescription	(	const char *	displayname,
		serdisp_wiredef_t *	wiredesc
	)

iterates through wiring definitions supported by display displayname
the iteration is started with assigning an empty string to wiredesc.name

Parameters

[in]	displayname	display name or alias name
[out]	wiredesc	address of wiring descriptor

Return values

1	successful
0	unsuccessful (no more wirings found)

Example:

 serdisp_wiredef_t wiredesc;
 wiredesc.name = "";
 
 while(serdisp_nextwiringdescription("PCD85644", &wiredesc)) {
   printf("%s\n", wiredesc.name);
 }

Since: 1.96

void serdisp_quit ( serdisp_t * dd )

clears and switches off the display and releases the output device

Parameters

dd	device descriptor

Since: 1.93

int serdisp_reset ( serdisp_t * dd )

Parameters

dd	device descriptor

Return values

1	successful reset
0	unsucessful reset

void serdisp_rewrite ( serdisp_t * dd )

Parameters

dd	device descriptor

void serdisp_setoption	(	serdisp_t *	dd,
		const char *	optionname,
		long	value
	)

change a display option (replaces serdisp_feature())

Parameters

dd	device descriptor
optionname	name of option to change
value	value for option

Since: 1.96

void serdisp_setpixel	(	serdisp_t *	dd,
		int	x,
		int	y,
		long	colour
	)

Parameters

dd	device descriptor
x	x-position
y	y-position
colour	colour representation dependent on colour-scheme in use monochrome: 0: pixel not set, <>0: pixel set greyscale: if not 256 colours: index of greyvalue, else greyvalue indexed colour: index of colour-entry packed colour: packed representation (eg. RGB444, RGB332, ...) true colour: eg. 0xAARRGGBB (dependend on RGB-scheme (RGB, BGR, ..)

Attention: this function is hardware dependent!
for hardware independent pixel changing serdisp_setsdcol() should be used.

Deprecated:: The byte size of colour is architecture dependent.
Architecture independent function serdisp_setsdpixel() should be used instead.

void serdisp_setpixels	(	serdisp_t *	dd,
		int	x,
		int	y,
		int	w,
		int	h,
		byte *	data
	)

Parameters

dd	device descriptor
x	x-position top/left
y	y-position top/left
w	width of content
h	height of content
data	pixel/colour data (one byte == one pixel)

Deprecated:: this function only works with dephts <= 8 and will be replaced through better functions

void serdisp_setsdpixel	(	serdisp_t *	dd,
		int	x,
		int	y,
		SDCol	sdcol
	)

Parameters

dd	device descriptor
x	x-position
y	y-position
sdcol	colour representation dependent on colour-scheme in use monochrome: 0: pixel not set, <>0: pixel set greyscale: if not 256 colours: index of greyvalue, else greyvalue indexed colour: index of colour-entry packed colour: packed representation (eg. RGB444, RGB332, ...) true colour: eg. 0xAARRGGBB (dependend on RGB-scheme (RGB, BGR, ..)

Attention: this function is hardware dependent!
for hardware independent pixel changing serdisp_setsdcol() should be used.

Since: 1.98.0

void serdisp_update ( serdisp_t * dd )

Parameters

dd	device descriptor

Macros

Device handling functions

Library version

Drawing functions

Get/Set display settings and informations

Display options

Backward Compatibility functions

Deprecated functions

Detailed Description

Introduction

Macro Definition Documentation

Function Documentation