= RTEMS Graphics Toolkit =

[[TOC(Projects/GraphicsToolkit, depth=2)]]


The RTEMS Graphics Toolkit is a collection of graphics libraries to facilitate building graphics applications with RTEMS.  See [http://rtemsramblings.blogspot.com/2010/01/rtems-graphics-toolkit.html Joel's January 2010 Blog Post] for more information.

CVS Module: rtems-graphics-toolkit

The RTEMS Graphics Toolkit include

 *  libjpeg - (v7) http://www.ijg.org/
 *  libtiff - (v3.6.2) http://www.libtiff.org/
 *  libpng - (1.2.42) http://www.libpng.org/pub/png/libpng.html
 *  libfreetype - (2.3.11) http://freetype.sourceforge.net/index2.html
 *  libt1 - (5.1.2) http://www.t1lib.org/

!Microwindows/Nano-X may be built using the kit but you must download that separately from their GIT Repository

The following packages are included but not currently ported:

 *  mmap_kit - our own invention to provide things needed by svgalib before these are merged into RTEMS
 *  svgalib - (1.4.3) http://svgalib.org/
 *  fltk - (1.1.10) http://www.fltk.org/

We need nxlib from Microwindows to build fltk.  This will require us creating a small kit of X11 .h files and fonts so nxlib will build and run.  Then fltk should just build and work.

Official !MicroWindows/Nano-X Gregory Haerr's repository on !GitHub: https://github.com/ghaerr/microwindows

Development version with integrated RTEMS support/updates for multiple !MicroWindows/Nano-X: https://github.com/ppisa/microwindows/tree/rtems-ppisa

'''Acknowledgements'''

 *  Rosimildo !DaSilva did the initial port of Microwindows to RTEMS 4.5.
 *  Roxana Leontie updated Rosimildo's work to 4.10 and worked to get the patches merged into the main Microwindows source base.
 *  [wiki:User:AaronGrier_  Aaron Grier] mentored Roxana in this effort.
 *  [wiki:TBR/User/JoelSherrill Joel Sherrill] provided advice and guidance.  He also developed the initial build infrastructure for the RTEMS Graphics Toolkit and ported the supporting libraries.
= Building The Kit =


Use the script "do_it" in the top directory.  It tries to build every currently support component for a specific BSP and install it with as little user intervention as possible.  This is its help:

{{{
$ ./do_it -?
./do_it: illegal option -- ?
do_it [options]
  -A - build and install all libraries
  -j - build JPEG support (default=no)
  -p - build PNG support (default=no)
  -t - build TIFF support (default=no)
  -1 - build Adobe Type 1 font support (default=no)
  -T - build Truetype font support (default=no)
  -n - build Microwindows/Nano-X support (default=no)
  -x - build Microwindows/Nano-X NXLib support (default=no)
  -f - build FLTK support (default=no)
  -c - clean after building (default=no)
  -v - verbose

NOTES:
  + Use of each option toggles the setting.  For example, \"-v -v -A -1\"
    results in verbose=no and all steps done except Type 1 fonts.
  + RTEMS_MAKEFILE_PATH must be set.
  + By default, nothing is built.
}}}

A sample invocation is shown below:

{{{
RTEMS_MAKEFILE_PATH=/home/joel/rtems-4.10-work/bsp-install/i386-rtems4.10/pc386/ ./do_it -A
}}}
= Component Details =
The RTEMS Graphics Toolkit has a variety of components in various states of usability on RTEMS.  For each component, there is a section following with details on:
||=Source =|| The version ||
||=Origin =|| Where did it come from? ||
||=Included in kit source =|| Is it in our CVS module or do you fetch it separately. ||
||=Status =|| Status of RTEMS support. ||

= JPEG Graphics Support =
[[Image(http://1.bp.blogspot.com/_5Tmc8sBljXU/S1ev2i9Vm4I/AAAAAAAAADs/2KJTFe3Y-fo/s1600/gumstix-rtems.png, right, 200px)]]

The image on the right is a screen capture of the Microwindows nxview demo running on the ARM/Gumstix BSP on the Skyeye simulator displaying the RTEMS logo in JPEG format.

||=Source =|| libjpeg v7 in Kit ||
||=Origin =|| http://www.ijg.org/ ||
||=Included in kit source =|| Yes. ||
||=Status =|| Working. Built by ''do_it'' ||

= TIFF Graphics Support =

||=Source =|| libtiff v3.6.2 ||
||=Origin =|| http://www.libtiff.org/ ||
||=Included in kit source =|| Yes. ||
||=Status =|| Working. Built by ''do_it'' ||

= PNG Graphics Support =

||=Source =|| libpng 1.2.42 ||
||=Origin =|| http://www.libpng.org/pub/png/libpng.html ||
||=Included in kit source =|| Yes. ||
||=Status =|| Working. Built by ''do_it'' ||

= Freetype Library =

||=Source =|| libfreetype 2.3.11 ||
||=Origin =|| http://freetype.sourceforge.net/index2.html ||
||=Included in kit source =|| Yes. ||
||=Status =|| Working. Built by ''do_it'' ||

= Adobe Type 1 Font Support =

||=Source =|| libt1 5.1.2 ||
||=Origin =|| http://www.t1lib.org/ ||
||=Included in kit source =|| Yes. ||
||=Status =|| Working. Built by ''do_it'' ||

= !Microwindows/Nano-X =

[[Image(http://2.bp.blogspot.com/_5Tmc8sBljXU/S1evslcmVHI/AAAAAAAAADk/Ufb1xKfxJYM/s1600/gumstix-mine.png, right, 200px)]]
The image on the right is a screen capture of the Microwindows minesweeper demo running on the ARM/Gumstix BSP on the Skyeye simulator.

||=Source =|| microwin HEAD ||
||=Origin =|| http://www.microwindows.org/ ||
||=Included in kit source =|| Not currently. Fetch from their git repository. ||
||=Status =|| Working. Built by ''do_it'' ||

The source may be fetched with the following command:

{{{
git clone git://microwindows.org/microwin
}}}

= RTEMS X11 Kit =

||=Source =|| not yet ||
||=Origin =|| TBD ||
||=Included in kit source =|| Not currently.  Will be when implemented. ||
||=Status =|| Needs to be built. ||

This will contain the X11 header files and fonts needed by nxlib and fltk.  It is a prerequisite for supporting those.

= NXLib =

||=Source =|| nxlib HEAD ||
||=Origin =|| http://www.microwin.org ||
||=Included in kit source =|| Not currently. Fetch from their git repository. ||
||=Status =|| Building. Built by ''do_it'' script. ||

Provides "RTEMS X11 Kit".

The source may be fetched with the following command:

{{{
git clone git://microwindows.org/nxlib
}}}

= MMap Kit =

||=Source =|| mmap_kit directory ||
||=Origin =|| RTEMS Project ||
||=Included in kit source =|| Yes. ||
||=Status =|| Needs work. ||

The purpose of this package is to provide implementations of ''sys/mman.h'' and other things required by svgalib.  When working, these can be merged into RTEMS proper and this component deleted.

= SVGA Library =

||=Source =|| svgalib 1.4.3 ||
||=Origin =|| http://svgalib.org/ ||
||=Included in kit source =|| Yes. ||
||=Status =|| Needs work. ||

We have added a Makefile.rtems and instructions.  It needs work and supporting methods and .h files which are being added to ''mmap_kit''.  The goal is to minimize modifications to this package. 

We need this to have better video drivers.  The pc386 video frame buffer driver is 16 color 640x480 VGA.  It also looks like this can be built for other architectures.
= FLTK =

||=Source =|| fltk 1.1.10 ||
||=Origin =|| http://www.fltk.org/ ||
||=Included in kit source =|| Yes. ||
||=Status =|| Pending port of nxlib ||

This includes a GUI builder and widgets.  This is the real baseline for building a GUI application.

= Experimental GSoC 2012 Version of the RTEMS Graphics Toolkit =

Alexandru-Sever Horin worked on graphics packages integration during 2012 summer.
Code is available from his [https://github.com/alex-sever-h GitHub repository]
until integration into mainline version of RTEMS Graphics Toolkit.

{{{
git clone https://github.com/alex-sever-h/rtems-graphics-toolkit.git
cd rtems-graphics-toolkit
git clone https://github.com/alex-sever-h/microwin.git
git clone https://github.com/alex-sever-h/nxlib.git
export RTEMS_MAKEFILE_PATH=/opt/rtems4.11/i386-rtems4.11/pc686/
./do_it -A
}}}

Next packages and their versions are integrated:
fltk-1.3.0, jpeg-8d, t1lib-5.1.2,
freetype-2.4.10, libpng-1.5.12, tiff-4.0.2

GIT versions of !Microwindows/Nano-X 0.93dev + NXlib are used.

= Running RTEMS Graphics Toolkit on Raspberry Pi =

Raspberry Pi support for RTEMS graphic output has been developed during GSoC 2015 by Yang Qiao.
See project description on [wiki:GSoC/2015/rpi_graphic Raspberry Pi Graphics] page.

= Running RTEMS Graphics Toolkit under QEMU =

== RTEMS 4.10 and Cirrus GD5446 driver ==

Development version of RTEMS pc386 (pc[3456]86) BSP includes [http://git.rtems.org/rtems/tree/c/src/lib/libbsp/i386/pc386/console/fb_cirrus.c Cirrus GD5446 driver].
This driver is alternative to bare (planar) VGA driver and provides support for linear mapping of framebuffer and 16, 24 and 32 BPP support.
The Cirrus GD5446 driver can be selected during RTEMS configure when option USE_CIRRUS_GD5446=1 is set.

Example of a full configuration command used for RTEMS Graphics Toolkit under QEMU

{{{
../rtems/configure USE_CIRRUS_GD5446=1 --target=i386-rtems4.11 --prefix=/opt/rtems4.11 \
  --enable-rtems-inlines --disable-multiprocessing --enable-cxx \
  --enable-rdbg --enable-maintainer-mode --enable-networking --enable-posix \
  --enable-itron --disable-ada --disable-expada --disable-multilib --disable-docs \
  --enable-rtemsbsp=pc686
make
make install
}}}

QEMU wrapper script '''pc386''' from [http://git.rtems.org/rtems-testing/ '''rtems-testing'''] allows to start
application with graphic user interface when option '''-D''' is used. Example to start basic !Microwindows/Nano-X
demo from RTEMS Graphics Toolkit

{{{
/path/to/pc386 -D -i /path/to/build/rtems-graphics-toolkit/microwin/src/bin/demo
}}}

== RTEMS 4.11 and VESA BIOS Extension (VBE) ==

As of RTEMS 4.11 the VESA BIOS based graphics is the default for pc386 bsp (older USE_CIRRUS_GD5446=1 continues to be build time alternative).

The graphic mode is selected at RTEMS executive startup by kernel command line

{{{
--video=auto
}}}

or the default mode can be specified directly in application by fill of the global variable

{{{
const char * const rtems_fb_default_mode="auto";
}}}

All possible options for command line or variable initializer are
 * auto - the attached monitor DDC supported modes list is read and matched to the graphic
   card provided capabilities, it should choose native resolution mode for displays which provide such entry
   and corresponding mode is supported by a card
 * off - do not initialize graphics - because mode switch is possible only during startup this means that graphic output is disabled
 * 1024x768-32 etc - manual selection of the mode and color depth

The graphic support is disabled (off option) if nothing is specified on command line
or by application. Consult comments in driver driver source for more information
[https://git.rtems.org/rtems/tree/c/src/lib/libbsp/i386/pc386/console/fb_vesa_rm.c VBE graphic driver].

Implementation and more alternatives are documented in Jan Dolezal's thesis work
[https://dspace.cvut.cz/bitstream/handle/10467/61467/F3-BP-2015-Dolezal-Jan-Drivers-and-Libraries-Enabling-RTEMS-OS-GUI-on-Current-PC-Graphics-Cards.pdf Drivers and Libraries Enabling RTEMS OS GUI on Current PC Graphics Cards] and related Doxygen generated documentation
[https://dspace.cvut.cz/bitstream/handle/10467/61467/F3-BP-2015-Dolezal-Jan-priloha-Documentation-RTEMS-i386-VBE-framebuffer-support.pdf RTEMS i386 VBE Framebuffer Support].

= Open Projects =


If you are interested in any of these, ask on the list or one of the developers.  These have been identified as desirable and the next logical things to do.

 *  svgalib port
 *  X11 kit - Rather than port X11 to RTEMS, it seems like it would be more feasible to package the necessary collection of X11 headers and fonts for RTEMS and NXLIB.
 *  NXLIB port -- (requires RTEMS X11 Kit) NXLIB is a binary replacement for the libX11 library to allow applications to be run under Nano-X instead of full-blown X11.  It assumes that a native port of the X Window System is available for the target in question, which is often the case for Linux, but not for RTEMS. 
 *  fltk port
 *  defining RTEMS pointing device driver interface
 *  Framebuffer and pointing device drivers for BSPs

Other graphical software which might be of interest to the RTEMS community but have not been evaluated for technical and licensing appropriateness are: 

 *  [http://qt.nokia.com/products/ Qt Embedded]: While the Qt/X11 port could likely be run under NXLIB, performance may be better with a native Nano-X port.

 *  [http://tinywidgets.sourceforge.net/ TinyWidgets]: Last updated in 2007, but source is still available.

 *  [http://www.wxwidgets.org/docs/ wxWidgets for Microwindows]: incomplete port, appears to need some work to make it threadsafe.

 *  [http://www.directfb.org/ directfb]: Linux' DirectFB API provides additional graphics acceleration and limited windowing support.  It may be possible to provide a similar API under RTEMS to allow porting of Linux DirectFB applications.
=  Licensing Table  =

The fields in this table are as follows:

 *  Project - name of project with hyperlink to it.
 *  License - software license used. May need to link to license text if dual-licensed or "other".
 *  Language - what programming language is this written in?
 *  Active - is the project active?
 *  OK w/RTEMS Static - Is the license compatible with a statically linked proprietary RTEMS application?
 *  OK w/RTEMS Technical - Does the code appear to be feasible to run on RTEMS? Does the code make assumptions that would render it unable to run on RTEMS?
 *  Notes - Anything else

||= Candidate =||= License =||= Language =||= Active =||= OK w/RTEMS Static =||= OK w/RTEMS Technical =||= Notes =||
|| [http://www.ijg.org/ libjpeg] || Other Open Source License || C || 01/13/2013 || TBD || None ||
|| [http://www.libtiff.org/ libtiff] || Other Open Source License || C || 09/22/2012 || TBD || None ||
|| [http://www.libpng.org/pub/png/libpng.html libpng] || Other Open Source License || C (C89) || 04/29/2013 || TBD || None ||
|| [http://www.ijg.org/ libjpeg] || Other Open Source License || C (C89) || 04/29/2013 || TBD || None ||
|| [http://freetype.sourceforge.net/index2.html libfreetype] || GPLv2/FreeType (like BSD) || C || 05/08/2013 || TBD || None ||
|| [http://www.t1lib.org/ libt1] || GPLv3 || C (C99) || TBD || TBD || None ||
|| [http://www.microwindows.org/ microwindows] || MPL + GPLv2 option || C || TBD || OK || None ||
|| nxlib || MPL + GPLv2 option || C || TBD || OK || None ||
|| svgalib || Public License || C || TBD || TBD || None ||
|| fltk || GPLv3 || C++ || TBD || TBD || None ||
|| GLSL || GPLv3 || C || TBD || TBD || None ||