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
serdisp_control.h ... accessing and controlling a display
serdisp_colour.h ... drawing on a display
messages, error handling, useful defines
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

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 post test 2 development tree)

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)

close the device occupied by serdisp

 sdcd     ... serdisp connect descriptor

serdisp_CONN_t*
SDCONN_import_PP (int directIO, int hport)

import 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.

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");

long
serdisp_getversioncode (void)

get version code of serdisplib

returns the version code

example:

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

void
serdisp_close (serdisp_t* dd)

close display but do NOT clear / switch off display. 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)

clear / switch off display and release output device

  dd     ... display descriptor

int
serdisp_reset (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

int
serdisp_getwidth (serdisp_t* dd)

get width of display

  dd     ... display descriptor

returns width of display in pixels

int
serdisp_getheight (serdisp_t* dd)

get height of display

  dd     ... display descriptor

returns height of display in pixels

int
serdisp_getcolours (serdisp_t* dd)

get amount of colours supported by the configuration currently used

  dd     ... display descriptor

returns the amount of supported colours

int
serdisp_getdepth (serdisp_t* dd)

get colour depth supported by the configuration currently used

  dd     ... display descriptor

returns the amount of supported colours

int
serdisp_getaspect (serdisp_t* dd)

get 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

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

change a display feature

  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);

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)

clear whole display

  dd     ... display descriptor

void
serdisp_update (serdisp_t* dd)

update whole display

  dd     ... display descriptor

void
serdisp_rewrite (serdisp_t* dd)

rewrite whole display

  dd     ... display descriptor

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

blink 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

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)

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);

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

get colour of pixel at (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)

get serdisp connect descriptor used by the display

  dd     ... display descriptor

returns serdisp connect descriptor

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!

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)

pack 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)

convert 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)

convert 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)

set a colour 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)

get 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)

set a 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)

get grey value at position x / y

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

returns 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

version information and useful defines:

(defined in serdisp_control.h)

   SERDISP_VERSION_MAJOR and SERDISP_VERSION_MINOR contain major and minor version information for serdisplib

   SERDISP_VERSION_EXTRA may be used for patched versions but will NOT be evaluated

   serdisplib version code SERDISP_VERSION_CODE is calculated using SERDISP_VERSION_MAJOR and SERDISP_VERSION_MINOR.
   SERDISP_VERSION_CODE(a,b) calculates a valid serdisplib version code.
   together with SERDISP_VERSION(a,b) SERDISP_VERSION_CODE may be used for asserts

example:

   /* only include code if serdisplib is at least version 1.93 */
   #if (SERDISP_VERSION_CODE >= SERDISP_VERSION(1,93))
     ...
   #endif

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_feature(dd, FEATURE_BACKLIGHT, FEATURE_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.95

DISCLAIMER

overview

license

API changes:

serdisplib v.1.92

serdisplib v.1.93

serdisplib v.1.95

supported displays

serdisp_connect.h: accessing an output device

introduction

functions

serdisp_control.h: accessing and controlling a display

introduction

functions

serdisp_colour.h: drawing on a display

introduction

defines

macros

functions

messages, error handling, useful defines

introduction

message and error handling

version information and useful defines:

examples

complete example:

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

documentation for former versions