documentation for serdisplib

DISCLAIMER

THIS IS EXPERIMENTAL SOFTWARE AND HARDWARE. USE AT YOUR OWN RISK. THE MAINTAINER(S) OF THESE PAGES AND THE DEVELOPER(S) OF SOFTWARE AND HARDWARE PRESENTED ON THESE PAGES CAN NOT BE HELD LIABLE UNDER ANY CIRCUMSTANCES FOR DAMAGE TO HARDWARE OR SOFTWARE, LOST DATA, OR OTHER DIRECT OR INDIRECT DAMAGE RESULTING FROM THE USE OF THIS SOFTWARE OR HARDWARE. IF YOU DO NOT AGREE TO THESE CONDITIONS, YOU ARE NOT PERMITTED TO USE OR FURTHER DISTRIBUTE THIS SOFTWARE OR TO USE ANY TEMPLATES FOR BUILDING HARDWARE PRESENTED HERE.

overview

license (this software is protected under the terms of the GPL license)
API changes ... API changes since first released version of serdisplib
supported displays

serdisp_connect.h ... accessing an output device

open/close a device		since
SDCONN_open()	opens a device for serdisplib
SDCONN_close()	closes a device
SDCONN_import_PP()	imports an existing, already opened parport device

serdisp_control.h ... accessing and controlling a display

defines		since
SERDISP_VERSION_CODE SERDISP_VERSION_MAJOR SERDISP_VERSION_MINOR	version information	v1.93
macros
SERDISP_VERSION()	calculates a serdisplib version code	v1.93
SERDISP_VERSION_GET_MAJOR() SERDISP_VERSION_GET_MINOR()	returns major and minor number of a version code	v1.96
device handling functions
serdisp_init()	initialises a display
serdisp_close()	closes the display without clearing its contents and without switching it off
serdisp_quit()	clears, switches off the display and releases the output device	v1.93
serdisp_reset()	re-initialises the display
serdisp_fullreset()	resets the display (closes and reopens device, fully re-initialises the display)	v1.96
serdisp_getSDCONN()	opens a device for serdisplib
drawing functions
serdisp_setpixel()	changes a pixel in the display buffer
serdisp_getpixel()	gets the hardware dependend colour-information of a pixel
serdisp_clearbuffer()	resets the internal display-buffer
serdisp_clear()	clears whole display
serdisp_update()	updates whole display
serdisp_rewrite()	rewrites whole display
serdisp_blink()	blinks the display
get/set display settings and informations
serdisp_getwidth()	gets width of display
serdisp_getheight()	gets height of display
serdisp_getcolours()	gets amount of supported colours
serdisp_getdepth()	gets colour depth	v1.95
serdisp_getpixelaspect()	gets pixel aspect ratio	v1.95
serdisp_getdisplayname()	gets the display name (unprocessed, spelling as it was used for `serdisp_init()`)	v1.96
serdisp_isdisplay()	tests if display is supported	v1.96
serdisp_getdisplaydescription()	gets display description	v1.96
serdisp_nextdisplaydescription()	iterates supported displays	v1.96
serdisp_currdisplaydescription()	gets display description for the active display	v1.96
display options
serdisp_getoption()	gets the value of a display option	v1.96
serdisp_setoption()	sets the value of a display option	v1.96
serdisp_isoption()	tests if option is supported	v1.96
serdisp_getoptiondescription()	gets a description to a given option	v1.96
serdisp_nextoptiondescription()	iterates options supported by the display	v1.96
deprecated functions		depr.
serdisp_setpixels()	changes an area in the display buffer	v1.95
serdisp_feature()	changes a display feature. superseded by `serdisp_setoption()`	v1.96

serdisp_colour.h ... drawing on a display

defines		since
SD_COL_BLACK SD_COL_WHITE SD_COL_RED SD_COL_GREEN SD_COL_BLUE	pre-defined colour values	v1.96
macros
serdisp_pack2ARGB()	packs alpha/red/green/blue values to a ARGB colour value	v1.95
serdisp_ARGB2GREY()	converts an ARGB colour value to the corresponding grey value	v1.95
serdisp_GREY2ARGB()	converts a grey value to a corresponding ARGB colour value	v1.95
get/set a pixel and conversion functions
serdisp_getcolour()	gets the colour value at a given position	v1.95
serdisp_getgrey()	gets the grey value at a given position	v1.95
serdisp_setcolour()	sets the colour value at a given position	v1.95
serdisp_setgrey()	sets the grey value at a given position	v1.95
serdisp_transcolour()	translates an ARGB colour value to a hardware dependend colour information	v1.96
serdisp_transgrey()	translates a grey value to a hardware dependend colour information	v1.96
serdisp_lookupcolour()	translates a hardware dependend colour information to an ARGB colour value	v1.96
serdisp_lookupgrey()	translates a hardware dependend colour information to a grey value	v1.96

messages, error handling, useful defines

macros		since
sd_runtime_error()	tests if a runtime error has occured	v1.93
sd_geterrormsg()	returns textual error information	v1.93
sd_getdebuglevel()	gets the debug level	v1.96
sd_setdebuglevel()	sets the debug level	v1.96
sd_setlogmedium()	sets the log medium for debug messages	v1.96

examples
documentation for former versions

license

This program is free software; you can redistribute it and/or modify   
it under the terms of the GNU General Public License as published by   
the Free Software Foundation; either version 2 of the License, or (at  
your option) any later version.                                        

This program is distributed in the hope that it will be useful, but    
WITHOUT ANY WARRANTY; without even the implied warranty of             
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU      
General Public License for more details.

A copy of the GPL is located inside the source code tree (file 'COPYING').

API changes:

serdisplib v.1.92

The additional support of direct I/O starting with version 1.92 requested a change in the API:
instead of int filehandles a structure ppd (parallel port descriptor) is now used.
serdisp_init() now has an extra parameter that will be used in the future.

serdisplib v.1.93

Starting with version 1.93, more output devices are supported (besides parallel port now also serial port for i2c-displays). This requested another API-change:

serdisp_parport.h, PP_open(), PP_close() and PP_write() where replaced through serdisp_connect.h, SDCONN_open(), SDCONN_close() and SDCONN_write()
also the descriptor serdisp_PP_t was renamed to serdisp_CONN_t
for limited backward compatibility serdisp_parport.h is still existing and contains defines that resemble the old names (but it is highly recommended to only use serdisp_connect.h)
no display descriptor fields should be accessed directly. so ONLY serdisp_quit() should be used for shutting down the output device (no more SDCONN_close(dd->sdcd);)
if the output device is needed at runtime or needs to be accessed, serdisp_getSDCONN() should be used (but please NOT dd->sdcd any more)

serdisplib v.1.95

Version 1.95 introduces future support for colour displays. This requested a small change in two major functions and a re-define of their tasks:

Parameter colour in serdisp_setpixel()/serdisp_getpixel() was changed from int to long. This should have no drawbacks in 32+ bit architectures, a recompile should do.
Type long will be the type for a colour in serdisplib. Format: #AARRGGBB -> one byte for alpha, red, green, and blue channel each.
serdisp_setpixel()/serdisp_getpixel() should no longer be used in applications because they process colour information in a hardware-dependend representation.
Instead of these serdisp_setcolour()/serdisp_getcolour() should be used in applications as they process colour information in a hardware-independend representation.
#include <serdisplib/serdisp.h>; includes all relevant serdisplib header files

serdisplib v.1.96

no API-changes in version 1.96.

the only change to an existing function: serdisp_reset() now only re-initialises the display whereas the newly added function serdisp_fullreset() closes and re-opens the device and fully re-initialises the display (the splitting into two functions was necessary to avoid an API-change. the former serdisp_reset() was rather buggy anyways ...)

deprecated function: serdisp_feature() has been superseded by serdisp_setoption().

further infos on changes: HISTORY and README

supported displays

see http://serdisplib.sourceforge.net/index.html#displays for a detailed overview.

serdisp_connect.h: accessing an output device

introduction

serdisp_connect.h offers some functions for opening and closing output devices using a descriptor ('sdcd').
supported access methods:

ioctl-calls: output devices are accessed using devices
direct I/O: output devices are accessed using port addresses (direct I/O is only supported with linux and i386/x86_64 architectures)

The default output-method uses 'ioctl'-calls using device names (eg: /dev/parport0).
serdisplib also supports using direct-IO (using port-addresses and inline-assembler).

pros and cons:

ioctl:
+ not restricted to root-only (users qualified for eg. /dev/parport0 may control a display connected to it)
+ universal (usable with more unix-derivats)
- slower than direct I/O
direct I/O:
+ faster (at least in theory)
- root-only
- i386-compliant architectures only (*bsd-support planned)

output devices:

parallel port
serial port (i2c-devices only)
USB-to-serial adaptors (i2c-devices only)

tested compilers:

gcc 2.96
gcc 3.x
gcc 4.0 (tested using fedora core 4)

operating systems (tested):

linux (direct I/O only with x86 architectures)
solaris 10 (only x86 tested. devices: ecpp and cua)
freebsd (only x86 and parport tested)

operating systems (untested):

linux / non-x86
freebsd/ non-86
openbsd (compiles on sourceforge's compile farm)

either the functions provided by serdisp_connect.h may be used or any other (non-serdisplib) function / code / ... that is returning either a file handle which may be controlled using ioctl-calls or direct I/O using outp-calls. to be able to use such a file handle together with serdisplib it has to to be imported using SDCONN_import_PP() (only parallel port supported for now).

functions

serdisp_CONN_t*
SDCONN_open (const char sdcdev[])

opens a device for serdisplib

 sdcdev  ...device name or port-number of device to open. 

                format:  protocol:device    (protocol is case insensitive)
 
                no protocol is needed for known devices (list below):

                /dev/parportX    PARPORT
                /dev/ppiX        PARPORT  (bsd)
                /dev/ecppX       PARPORT  (solaris)
                0x378            PARPORT  (first parallel port, linux, direct IO)
                0x278            PARPORT  (second parallel port, linux, direct IO)
                /dev/ttySX       SERRAW
                /dev/ttyUSBX     SERRAW
                /dev/cuaX        SERRAW
                0x3f8            SERRAW   (first serial port, linux, direct IO)
                0x2f8            SERRAW   (second serial port, linux, direct IO)

              examples:
                "/dev/parport0"           (parallel port, ioctl, linux)
                "0x378"                   (parallel port, direct IO, linux 86 only)
                "/dev/ecpp0"              (parallel port, ioctl, solaris)
                "/dev/ttyS0"              (serial port, ioctl, should be os-indepentend (POSIX))
                "0x3f8"                   (serial port, direct IO, linux x86 only)
 
                "serraw:/dev/ttyS0"       (serial device, ioctl)
                "SERRAW:/dev/ttyS0"       (the same as above because protocol is case-insensitive)
                "SERPORT:/dev/ttyS0"      (the same because SERPORT and SERRAW are synonyms)
                "serraw:0x3f8"            (serial device, direct IO)
                "parport:/dev/parport0"   (linux, ioctl)

returns a serdisp connect descriptor or (serdisp_CONN_t*)0 if operation was unsuccessful

void
SDCONN_close (serdisp_CONN_t* sdcd)

closes the device occupied by serdisp

 sdcd     ... serdisp connect descriptor

serdisp_CONN_t*
SDCONN_import_PP (int directIO, int hport)

imports an existing, already opened parport device / port and create a sdcd struct out of it.

USE WITH CARE!!! all permissions and stuff like that must be ok before!!
no checking for validity in here

 directIO   ... 1: yes -> outp-calls, 0: no -> ioctl-calls
 hport      ... if directIO: port (eg: 0x378), else: descriptor for parport dev

returns a serdisp connect descriptor or (serdisp_CONN_t*)0 if operation was unsuccessful

SDCONN_write() and SDCONN_read() are for internal use only and should not be used outside the library

serdisp_control.h: accessing and controlling a display

introduction

all elementary functions for controlling a display are defined here

NOTA BENE: only these functions should be used. no descriptor fields or internal functions should be accessed directly as these are subject to change.

defines

version information:

   SERDISP_VERSION_CODE    .. unified version code (major and minor version information packed into a single number)
   SERDISP_VERSION_MAJOR   .. major version of serdisplib
   SERDISP_VERSION_MINOR   .. minor version of serdisplib

macros

long
SERDISP_VERSION (short _major, short _minor)

calculates a serdisplib version code

  _major   ... major version
  _minor   ... minor version

returns the version code which is calculated using major and minor version information

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

short
SERDISP_VERSION_GET_MAJOR (long _code)

returns the major version information out of a serdisplib version code

  _code   ... serdisplib version code

returns major version information

short
SERDISP_VERSION_GET_MINOR (long _code)

returns the minor version information out of a serdisplib version code

  _code   ... serdisplib version code

returns minor version information

example:

   printf("version information of serdisplib header files: %d.%d\n", 
          SERDISP_VERSION_GET_MAJOR(SERDISP_VERSION_CODE), 
          SERDISP_VERSION_GET_MINOR(SERDISP_VERSION_CODE) 
         );

functions

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

initialises a display. all capabilities and basic values are set

  sdcd         ... output device handle
  dispname     ... display name (supported displays: look at section supported displays)
  optionstring ... option string (key-value pairs separated by semi-colons)

returns a display descriptor

example:

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

void
serdisp_close (serdisp_t* dd)

closes the display without clearing / switching it off. 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 either be called)

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
but: directIO works as expected (TxD will NOT be reset after program exit)
this is an operating system specific behaviour and canNOT be influenced (as it seems)

  dd     ... display descriptor

void
serdisp_quit (serdisp_t* dd)

clears and switches off the display and releases the output device

  dd     ... display descriptor

int
serdisp_reset (serdisp_t* dd)

re-initialises the display

  dd     ... display descriptor

returns 1 if reset was successful or 0 if not

serdisp_t*
serdisp_fullreset (serdisp_t* dd)

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

ATTENTION:

will not work if device was imported using SDCONN_import_PP()

  dd     ... display descriptor

returns 1 if reset was successful or 0 if not

void
serdisp_clearbuffer (serdisp_t* dd)

resets the internal display-buffer that is used by serdisplib
display will NOT be redrawn!

  dd     ... display descriptor

void
serdisp_clear (serdisp_t* dd)

clears the whole display

  dd     ... display descriptor

void
serdisp_update (serdisp_t* dd)

updates the whole display

  dd     ... display descriptor

void
serdisp_rewrite (serdisp_t* dd)

rewrites the whole display

  dd     ... display descriptor

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

blinks the the display

  dd     ... display descriptor
  what   ... 0: blinking using backlight, 1: blinking using display reversing
  cnt    ... how often should there be blinking
  delta  ... delay between two blinking intervals

long
serdisp_getversioncode (void)

gets version code of serdisplib (at compile time - in opposite to SERDISP_VERSION_CODE which represents the version code of the header files of serdisplib)

returns the version code

example:

   if (serdisp_getversioncode() >= SERDISP_VERSION(1,95)) {
     /* do something */
   }

int
serdisp_getwidth (serdisp_t* dd)

gets width of display

  dd     ... display descriptor

returns width of display in pixels

int
serdisp_getheight (serdisp_t* dd)

gets height of display

  dd     ... display descriptor

returns height of display in pixels

int
serdisp_getcolours (serdisp_t* dd)

gets the amount of colours that are supported by the configuration currently used

  dd     ... display descriptor

returns the amount of supported colours

int
serdisp_getdepth (serdisp_t* dd)

gets colour depth supported by the configuration currently used

  dd     ... display descriptor

returns the colour depth

int
serdisp_getaspect (serdisp_t* dd)

gets pixel aspect ratio in percent (to avoid floating-point values). using this value, distortions may be avoided when displaying pictures, ...

explanation:
most displays in cellphones have non-quadratic pixels. this function returns the ratio width:height (height = 100%).

examples:
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

  dd     ... display descriptor

returns pixel aspect ratio in percent

const char*
serdisp_getdisplayname (serdisp_t* dd)

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

  dd     ... display descriptor

returns the display name

int
serdisp_isdisplay (const char* displayname)

tests if display is supported

  displayname   ... name of display to test

returns 1 if display is supported or 0 if it is not

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

gets a description to a display

  displayname   ... name of display to test
  displaydesc   ... address of display descriptor where the information will be filled in
                  display descriptor fields:
                    char* dispname       .. main display name
                    char* aliasnames     .. alias option names, separated by ',' (eg.: 'SOMENAME,SM')
                    char* optionstring   .. default options used for initalisation
                    char* description    .. description text

returns 1 if display is available or 0 if display is unknown or 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);

int
serdisp_nextdisplaydescription (serdisp_display_t* displaydesc)

iterates supported displays

the iteration is started with assigning an empty string to optiondesc.dispname.

  displaydesc  ... address of display descriptor where the information will be filled in
                  display descriptor fields:
                    char* dispname       .. main display name
                    char* aliasnames     .. alias option names, separated by ',' (eg.: 'SOMENAME,SM')
                    char* optionstring   .. default options used for initalisation
                    char* description    .. description text

returns 1 if successful or 0 if no more display is available

example:

   serdisp_display_t displaydesc;
   displaydesc.dispname = "";   /* start the iteration with assigning an empty string before the first call */
   
   /* print all supported displays + aliasnames */
   while(serdisp_nextdisplaydescription(&displaydesc)) {
     printf("name: %s  aliases: %s\n", displaydesc.dispname, displaydesc.aliasnames);
   }

void
serdisp_currdisplaydescription (serdisp* dd, serdisp_display_t* displaydesc)

gets display description for the active display

  dd           ... display descriptor
  displaydesc  ... address of display descriptor where the information will be filled in
                  display descriptor fields:
                    char* dispname       .. main display name
                    char* aliasnames     .. alias option names, separated by ',' (eg.: 'SOMENAME,SM')
                    char* optionstring   .. options used for active display
                    char* description    .. description text

example:

   serdisp_display_t displaydesc;
   
   /* print all supported displays + aliasnames */
   serdisp_currdisplaydescription(dd, &displaydesc)) {
   printf("description of active display: %s\n", displaydesc.description);

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

gets the value of a display option

  dd           ... display descriptor
  optionname   ... name of option to get
  typesize     ... address of an integer variable where to store the type size of the option to get

returns the value of the option

example:

   char optionname[] = "ROTATE";
   int typesize;
   long value = serdisp_getoption(dd, optionname, &typesize);
   
   printf("value of option %s: %ld. its type size: %d\n", optionname, value, typesize);

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

sets the value of a display option

  dd          ... display descriptor
  optionname  ... name of option to set
  value       ... value of option to set
                  predefined constants:
                    SD_OPTION_NO      .. 0 (= switch off an option)
                    SD_OPTION_YES     .. 1 (= switch on an option)
                    SD_OPTION_TOGGLE  .. 2 (= toggle an option)

examples:

   /* invert display */
   serdisp_setoption(dd, "INVERT", SD_OPTION_YES);

   /* toggles backlight */
   serdisp_setoption(dd, "BACKLIGHT", SD_OPTION_TOGGLE);

   /* rotate 90 degrees */
   serdisp_setoption(dd, "ROTATE", 90);

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

tests if option is supported

  dd           ... display descriptor
  optionname   ... name of option to test

returns:

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

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

gets a description to a given option

  dd           ... display descriptor
  optionname   ... name of option to test
  optiondesc   ... address of option descriptor where the information will be filled in
                  option descriptor fields:
                    char* name       .. main option name
                    char* aliasnames .. alias option names, separated by ',' (eg.: 'SOMEOPTION,SO')
                    long  minval     .. minimum value allowed
                    long  maxval     .. maximum value allowed
                    long  modulo     .. modulo (only values that fullfil 'value MODULO modulo = 0' are allowed)
                    int   flag       .. SD_OPTIONFLAG_RW (read/write) or SD_OPTIONFLAG_RO (read-only)
                    char* defines    .. defines for option values, separated by ',' (eg.: '1=YES,0=NO')

returns 1 if option is available or 0 if option is unknown or unsupported

example:

   serdisp_options_t optiondesc;
   optionname = "DEPTH";
   
   int rc = serdisp_getoptiondescription(dd, optionname, &optiondesc);
   
   if (rc) {
     printf("the min/max values for option %s are: %ld/%ld\n", optionname, optiondesc.minval, optiondesc.maxval);
     
     if (optiondesc.flag & SD_OPTIONFLAG_RW)
       printf("the option value of %s may be modified\n", optionname);  
   }

int
serdisp_nextoptiondescription (serdisp* dd, serdisp_options_t* optiondesc)

iterates options supported by the display.

the iteration is started with assigning an empty string to optiondesc.name.

  dd           ... display descriptor
  optiondesc   ... address of option descriptor where the information will be filled in
                  option descriptor fields:
                    char* name       .. main option name
                    char* aliasnames .. alias option names, separated by ',' (eg.: 'SOMEOPTION,SO')
                    long  minval     .. minimum value allowed
                    long  maxval     .. maximum value allowed
                    long  modulo     .. modulo (only values that fullfil 'value MODULO modulo == 0' are allowed)
                    int   flag       .. SD_OPTIONFLAG_RW (read/write) or SD_OPTIONFLAG_RO (read-only)
                    char* defines    .. defines for option values, separated by ',' (eg.: '1=YES,0=NO')

returns 1 if successful or 0 if no more option is available

example:

   serdisp_options_t optiondesc;
   optiondesc.name = "";   /* start the iteration with assigning an empty string before the first call */
   
   /* print all supported options */
   while(serdisp_nextoptiondescription(dd, &optiondesc)) {
     printf("%s\n", optiondesc.name);
   }

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

changes a pixel in the display buffer

NOTA BENE:
this function is hardware dependend! for hardware independend programming use serdisp_setcolour()!

  dd     ... display descriptor
  x      ... x-position
  y      ... y-position
  colour ... monochrome: 0: clear (white), <>0: set (black); else: up to 16m colours (hardware dependend)

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

gets the colour value at position (x/y)

NOTA BENE:
this function is hardware dependend! for hardware independend programming use serdisp_getcolour()!

  dd     ... display descriptor
  x      ... x-position
  y      ... y-position

returns the hardware dependend colour information at (x/y)

serdisp_CONN_t*
serdisp_getSDCONN (serdisp_t* dd)

gets the serdisp connect descriptor used by the display descriptor

  dd     ... display descriptor

returns serdisp connect descriptor

deprecated functions

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

changes an area in the display buffer

DEPRECATED!
this functions only works for depths <= 8 and will be replaced through better functions

  dd     ... display 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)

examples:

   byte* data = .....;
   /* fill pixel/colour-data into 'data'
   ....
   ....

   /* draw a 5x5 area starting at position 5/10 */
   serdisp_setpixels(dd, 5, 10, 5, 5, data);

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

changes a display feature

DEPRECATED!
superseded by serdisp_setoption().

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

examples:

   serdisp_feature(dd, FEATURE_BACKLIGHT, FEATURE_TOGGLE);

   serdisp_feature(dd, CONTRAST, 5);

serdisp_colour.h: drawing on a display

introduction

all hardware-independend pixel manipulating functions are defined here

NOTA BENE:
serdisp_getpixel()/serdisp_setpixel() are hardware dependend functions.
to obtain hardware independend programs, serdisp_getcolour()/serdisp_setcolour(), which are defined in here, should be used!

only the functions described in here should be used because all other functions are either internal functions or subject to change!

defines

pre-defined colours:

   SD_COL_BLACK    .. 0xFF000000 (black)
   SD_COL_WHITE    .. 0xFFFFFFFF (white)
   SD_COL_RED      .. 0xFFFF0000 (red)
   SD_COL_GREEN    .. 0xFF00FF00 (green)
   SD_COL_BLUE     .. 0xFF0000FF (blue)

macros

long
serdisp_pack2ARGB (byte _a, byte _r, byte _g, byte _b)

packs an alpha/red/green/blue-representation to a colour representation understood by serdisplib

  _a   ... alpha-channel
  _r   ... red-channel
  _g   ... green-channel
  _b   ... blue-channel

returns colour value (hardware-independend, format: 0xAARRGGBB, AA .. alpha, RR .. red, GG .. green, BB .. blue)

example:

   int r = 0xFF;
   int g = 0x00;
   int b = 0x00;
   serdisp_setcolour(dd, 10, 20, serdisp_pack2ARGB("0xFF", r, g, b)); /* set pixel to red */

byte
serdisp_ARGB2GREY (long _col)

converts a colour value to a greylevel value

  _col   ... colour, format 0xAARRGGBB, AA .. alpha, RR .. red, GG .. green, BB .. blue

returns grey value

long
serdisp_GREY2ARGB (byte _grey)

converts a greylevel value to a colour value

  _grey   ... grey value

returns colour value, format 0xAARRGGBB, AA .. alpha, RR .. red, GG .. green, BB .. blue

functions

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

sets the colour value at position x/y

  dd     ... display descriptor
  x      ... x-position
  y      ... y-position
  colour ... colour  (hardware-independend, format: 0xAARRGGBB, AA .. alpha, RR .. red, GG .. green, BB .. blue)

examples:

   serdisp_setcolour(dd, 10, 20, 0xFFFF0000); /* set pixel to red */
   serdisp_setcolour(dd, 10, 20, SD_COL_RED); /* the same */

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

gets the colour value at position x / y

  dd     ... display descriptor
  x      ... x-position
  y      ... y-position

returns colour value (hardware-independend, format: 0xAARRGGBB, AA .. alpha, RR .. red, GG .. green, BB .. blue)

void
serdisp_setgrey (serdisp_t* dd, int x, int y, byte grey)

sets the grey value at position x/y

  dd     ... display descriptor
  x      ... x-position
  y      ... y-position
  grey   ... grey value (format: [0, 255])

examples:

   serdisp_setgrey(dd, 10, 20, 0xCC); /* set pixel to light grey */

byte
serdisp_getgrey (serdisp_t* dd, int x, int y)

gets the grey value at position x / y

  dd     ... display descriptor
  x      ... x-position
  y      ... y-position

returns grey value

long
serdisp_transcolour (serdisp_t* dd, long colour)

translates an ARGB colour value to a hardware dependend value that is suitable for serdisp_setpixel()

  dd        ... display descriptor
  colour    ... ARGB colour value

returns a translated, serdisp_setpixel()-compliant colour value

long
serdisp_transgrey (serdisp_t* dd, byte greyvalue)

translates a grey value to a hardware dependend value that is suitable for serdisp_setpixel()

  dd        ... display descriptor
  greyvalue ... grey value

returns a translated, serdisp_setpixel()-compliant colour value

long
serdisp_lookupcolour (serdisp_t* dd, long colour)

looks up the corresponding ARGB colour value to a serdisp_setpixel()-compliant colour value

  dd        ... display descriptor
  colour    ... serdisp_setpixel()-compliant colour value

returns a translated colour value (format: 0xAARRGGBB)

byte
serdisp_lookupgrey (serdisp_t* dd, long colour)

looks up the corresponding ARGB colour value to a serdisp_setpixel()-compliant colour value

  dd        ... display descriptor
  colour    ... serdisp_setpixel()-compliant colour value

returns an 8-bit grey value

messages, error handling, useful defines

introduction

serdisplib uses syslog for reporting debugging information, errors and warnings.
thus, /var/log/messages (or /var/adm/messages depending on operating system used) may contain useful informations.

message and error handling

(defined in serdisp_messages.h)

int
sd_runtime_error ()

returns 1 if a runtime error has occured (display drawing is stopped after a runtime error and may be reset using serdisp_reset())

char*
sd_geterrormsg ()

if an action was unsuccessful this function will return error information

int
sd_getdebuglevel ()

gets the debug level

returns the debug level

void
sd_setdebuglevel (int _level)

sets the debug level

_level ... constant which sets the debug level: SD_LVL_WARN = 0 .. only write warning informations SD_LVL_INFO = 1 .. more verbose debugging SD_LVL_VERBOSE = 2 .. verbose debugging

examples:
sd_setdebuglevel(SD_LVL_VERBOSE);

void
sd_setlogmedium (int _medium)

sets the log medium for debug messages

_medium ... constant which sets the log medium used for debugging information: SD_LOG_SYSLOG .. syslog SD_LOG_STDERR .. stdout SD_LOG_STDOUT .. syslog

examples:
sd_setdebuglevel(SD_LVL_INFO); /* write debugging info to stderr instead of using syslog (default) */ sd_setlogmedium(SD_LOG_STDERR);

examples

complete example:


#include <stdio.h>
#include <stdlib.h>

#include "serdisplib/serdisp.h"   /* include all important header files */

int main(int argc, char **argv) {

  char sdcdev[] = "/dev/parport0";  /* use parallel port */
  /*char sdcdev[] = "/dev/ttyS0";*/  /* use serial port */

  char dispname[] = "PCD8544";  /* display name */

  serdisp_CONN_t* sdcd;
  serdisp_t* dd = 0;
  int i;

  /* opening the output device */             
  sdcd = SDCONN_open(sdcdev);
                
  if (sdcd == (serdisp_CONN_t*)0) {        
    fprintf(stderr, "Error opening %s, additional info: %s\n", sdcdev, sd_geterrormsg());
    exit (1);
  }

  /* opening and initialising the display */
  dd = serdisp_init(sdcd, dispname, "");
  if (!dd) {
    SDCONN_close(sdcd);
    fprintf(stderr, "Error opening display %s, additional info: %s\n", dispname, sd_geterrormsg());
    exit(1);
  }


  /* turning on backlight */
  serdisp_setoption(dd, "BACKLIGHT", SD_OPTION_YES);

  /* clearing the display */
  serdisp_clear(dd);

  /* draw a border (only internal display buffer is affected!!) */
  for (i = 0; i < serdisp_getwidth(dd); i++) {
    serdisp_setcolour(dd, i, 0, SD_COL_BLACK);
    serdisp_setcolour(dd, i, serdisp_getheight(dd)-1, SD_COL_BLACK);
  }  
  for (i = 1; i < serdisp_getheight(dd)-1; i++) {
    serdisp_setcolour(dd, 0, i, SD_COL_BLACK);
    serdisp_setcolour(dd, serdisp_getwidth(dd)-1, i, SD_COL_BLACK);
  }

  /* commit changes -> update the display using the internal display buffer */
  serdisp_update(dd);

  /* wait 30 seconds */
  sleep(30);

  /* shutdown display and release device*/
  serdisp_quit(dd);
  
  return(0);
}

open display, draw something, and exit without clearing display:


  /* initialising, a.s.o.: see example above */
  ...

  /* draw something */
  ...


  /* commit changes -> update the display using the internal display buffer */
  serdisp_update(dd);

  /* release display without switching it off / clearing it */
  serdisp_close(dd);

  exit(0);

documentation for serdisplib >= V 1.96

DISCLAIMER

overview

license

API changes:

serdisplib v.1.92

serdisplib v.1.93

serdisplib v.1.95

serdisplib v.1.96

supported displays

serdisp_connect.h: accessing an output device

introduction

functions

serdisp_control.h: accessing and controlling a display

introduction

defines

macros

functions

deprecated functions

serdisp_colour.h: drawing on a display

introduction

defines

macros

functions

messages, error handling, useful defines

introduction

message and error handling

examples

complete example:

open display, draw something, and exit without clearing display:

documentation for former versions