Skip to content

Home News Screenshots Wiki Themes Bugtracker Members Logos Search
  You are not logged in Link icon Log in Link icon Join
You are here: Home » PicoGUI Wiki » FAQ

Log in


This is the Frequently Asked Questions list for PicoGUI. If you have new questions and/or answers, log in to the Wiki and add them.

What is PicoGUI?

PicoGUI is a new Graphical User Interface architecture designed with embedded systems in mind. The scope of the project includes low-level graphics and input, widgets, themeing, layout, font rendering, network transparency, and debugging features. To make an analogy with other GUI systems, PicoGUI would be similar to any of the following:
  • XFree86? + GTK + a window manager
  • Microwindows + FLTK
  • Qt/Embedded

What's so different about PicoGUI's architecture?

Since PicoGUI's architecture was designed completely from scratch, we had the opportunity to make a lot of unconventional design decisions that hopefully make PicoGUI a really nifty GUI. Here are some of the more important things:

  • PicoGUI is client-server, but the separation between the two halves is drastically different than in X.

In X, the server maintains very little state information and only performs low-level drawing commands. This means that the server is very flexible, but that client-server bandwidth is high and the client code has to be complicated. Extra code on the client side becomes impractical on systems without shared libraries, and it usually locks you into implementing clients with a single language until wrappers are written for other programming languages.

PicoGUI's approach is to put everything possible on the server side. Widgets, themes, even custom graphics are all implemented on the server side. The client library's only purpose is to give a convenient way to access the server's API. This makes the server less flexible, but client-server bandwidth is very small. The server code can be tightly integrated, small, and efficient. Since it is easy to write client libraries, the user will have a choice of many programming languages for applications.

To get an idea of how much is implemented completely on the server side, try stopping an application with ^Z while it's running. You'll still be able to resize, scroll, and move the app. You can still click buttons, though they will have no effect until the client is resumed.

This has several advantages, including consistency, speed, language independence, and the ability for the server to synchronize and optionally double-buffer all graphics.

  • PicoGUI enforces a separation of content and presentation

Most GUIs?, especially common toolkits for embedded systems, make you specify widgets in terms of x,y coordinates, and the widget's look is hardcoded into the toolkit. This means that both the toolkit's code and the application are making assumptions about not only the user's preference, but the hardware's capabilities.

PicoGUI uses its layout engine and theme system to combat this problem. The layout engine forces the application programmer to define widgets' size and position in relative terms in most circumstances, so that the GUI makes no assumptions about the display's units. The theme system offloads almost all specification of widget sizes, behavior, and appearance to the themes. PicoGUI's themes are a simple database combined with a very simple programming language. Themes define objects that have inheritance, and multiple themes can be loaded at one time.

  • PicoGUI's video driver architecture lets the driver author choose how many assumptions PicoGUI should make

PicoGUI defines a large number of functions as its "Video Library". (47 at the time of this writing) This includes simple pixel, line, and rectangle primitives, blits, sprites, bitmap representation, and more. The default implementation of these functions, "defaultvbl", makes almost no assumptions about the actual capabilities of the video device. This means that by redefining selected functions you can have PicoGUI send video output over a serial port, or override the built-in bitmap fonts with FreeType antialiased fonts. Additionally, there is a set of "Video Base Libraries" that make supporting common hardware easy. There are VBLs for various linear and planar framebuffers.

There are a lot of neat advantages to this. It's easy for picogui to change depth and resolution on the fly, or add extra layers to the video driver stack for handling rotation, for example. Everything's done on the fly, so there's never a reason to restart the PicoGUI server.

  • PicoGUI supports alternative application management paragigms

Traditionally PicoGUI applications occupy "panels" that can be resized and rotated, but never overlap. This optimizes the available screen space and the amount of time users spend rearranging apps. PicoGUI's modular app management system also supports traditional overlapping windows (using video drivers that support them) and will in the future support other paradigms like those used by ion and blender.

  • Overall goal of scalability

Probably the "big picture" difference between PicoGUI and other embedded GUI projects is that PicoGUI is designed with scalability in mind. Because of its layout engine, theme engine, and video driver architecture, PicoGUI can run on a mind-boggling array of hardware from a handheld, to a typical desktop computer, to a wallclock.

Once PicoGUI is capable of running on desktop computers either in a rootless mode inside X/Win32/Quartz or running as a full desktop GUI, users will be able to take the same application they run on a PDA, and run it on their desktop, cellphone, car, etc.

What does PicoGUI run on?


In theory, PicoGUI could run on almost anything. The driver architecture is very flexible, and the code doesn't use many OS-specific features. The following lists a few selected extremes from various categories. It is by no means a complete list. (at the time of this writing PicoGUI has 15 different input drivers!)

Video: * Linux framebuffer

  • In a window using SDL or X11
  • ncurses
  • OpenGL
  • Hardware-specific framebuffers with optional acceleration

Input: * Standard mouse and keyboard

  • Keyboard (or buttons) only
  • Network input device

CPU: * 16mHz Dragonball EZ

Operating System: * Linux

  • NetBSD?
  • MacOS? X

There's a partial list of systems PicoGUI runs on at:

How big is PicoGUI?

Almost all of PicoGUI's code is in the "pgserver" binary. Remember that the single pgserver binary includes fonts, and has a similar scope of capabilities to an X server plus a widget toolkit and a few other libraries. The size really depends on the compile time options selected (there are a great many), the CPU targeted, and the binary format. Here are some examples, all stripped ELF binaries for Linux:

|Configuration|CPU|pgserver size|






The other components of PicoGUI are applications, themes, and client libraries. Applications are small since the client API is thin. Themes are also usually small, but it depends on the amount and type of extra data contained in them. Here are some more examples:


|C client library|x86|47k (mostly shared lib overhead?)|

|Pseudo-3D theme|n/a|2.4k|

|PicoAqua theme|n/a|37k|

|Hello World app|x86|3.8k|

|Dialog Demo app|x86|8.0k|

How does PicoGUI compare to Fresco?

Fresco is another GUI ( that has some similarities to PicoGUI. Fresco has been around for quite a while longer than PicoGUI, but when PicoGUI was started MicahDowty? didn't know about Fresco.
  • Similarities between PicoGUI and Fresco
    • Standard widgets on the server side
    • Separation between applications and device coordinates
    • Server keeps a scene graph
    • New GUI architecture, with no backward compatibility
    • Language-independent client/server protocol
  • Differences between PicoGUI and Fresco
    • PicoGUI takes a lot of shortcuts compared to Fresco, to make it more suitable for embedded systems
    • Fresco uses device independent coordinates everywhere, while PicoGUI's themes and layout engine still use pixels
    • Fresco uses CORBA, while PicoGUI has its own network protocol
    • There's nothing like PicoGUI's theme interpreter in Fresco
    • Fresco handles overlapping, and uses a homogeneous scene graph making it more suitable for generic drawing apps and desktop window management
    • PicoGUI has features tailored for embedded systems, such as support for low-end display hardware, and keyboard-only navigation
    • Fresco does real transparency, while PicoGUI usually cheats :)
    • Fresco relies heavily on floating point math, PicoGUI's core is 100% integer. Of course this means that picogui's layout engine has to operate in integer pixel units. (See below)

Is PicoGUI really 100% integer? What about subpixel font layout, and alpha blending?

All required components of picogui are 100% integer, and almost all optional components. The only parts of the picogui server that use floating point are:
  • The freetype font engine uses floating point math at initialization to build gamma correction tables
  • The sdlgl video driver and ftgl font engine require floating point for OpenGL

The subpixel font layout and alpha blending are done with fixed point math, so they are fast even on CPUs? with no floating point unit.

How hard is it to port X/Gtk/Qt apps to PicoGUI?

Well, PicoGUI isn't designed to be easy to port software to, it's designed to be a completely new GUI architecture. In general it would be very difficult to port a Gtk app, for example, to PicoGUI. However there are of course exceptions. If the app has a good separation of it's GUI code it might be easy to port. X-Chat is a good example of a Gtk app that was ported to PicoGUI because the GUI was well-separated.

How do you develop and debug PicoGUI apps? Is there an emulator?

Since PicoGUI runs natively on desktop computers just fine, there's no need for an actual emulator under most circumstances. You can simply run PicoGUI on the desktop (usually in a window, using the "sdlfb" driver) and it should run just like it does on your embedded system. However, the sdlfb driver does have a useful feature to make it emulate the look and feel of an embedded system. See README.skins in the pgserver distrobution.

When i run ./ it gives me errors!

Sorry, that's a known problem with the build system. Ignore the errors and it should work fine.

What kind of configuration options do picogui support?

pgserver has two big categories of config options:
  • Compile-time options. Run "make menuconfig" to edit them. Most options have attached descriptions you can access with the "help" button. There are sample configurations for several architectures in the "profiles" directory.
  • Run-time options. Read the README.configfile and the output of "pgserver -h" for info on these. All run-time options can be specified in a config file or on the command line.

I ran pgserver, but all i get is this white empty box!

That's what pgserver looks like without any themes or applications loaded. Themes can be loaded in three ways:
  • In the configuration file. See README.configfile
  • With the -t command line option to pgserver
  • At runtime, with the pgLoadTheme() function

Applications can be run from the command line as usual. If you want to start an application automatically with pgserver, you can use the -s command line option or the "session" config variable.

What makes PicoGUI better than Microwindows or Qt/Embedded?

* PicoGUI can run on a very wide range of devices, including very low-end hardware
  • PicoGUI includes integrated widgets and themes
  • PicoGUI is under very active development in an open community
  • PicoGUI is a completely new architecture for embedded systems, instead of an existing architecture that has been adapted for the embedded world
  • The low-bandwidth client-server connection makes PicoGUI good for thin clients
  • PicoGUI lets you choose any language for client development. The C client library is most mature, though there's a new Python library that already works quite well. There is a Perl client library, but it needs a rewrite.

What makes Microwindows or Qt/Embedded better than PicoGUI?

* PicoGUI is still very young for a project with such a broad scope. There is still a lot of work left to be done.
  • There are many features missing from pgserver still
  • There aren't many applications for picogui yet
  • There's currently a lack of documentation

Hopefully all of these deficiencies in PicoGUI can be solved with time.

How can I help with PicoGUI?

Join the pgui-devel mailing list, visit us in the #picogui IRC channel on, add ideas to this Wiki. Any sort of help will be appreciated, but right now we're most in need of the following types of help:
  • Programmers to write PicoGUI applications Authors/Programmers to write and/or maintain documentation for PicoGUI Volunteers to create packages and linux distrobutions featuring PicoGUI * Artists (preferably with some programming experience) to create picogui themes

Does PicoGUI require a pointing device?

No. PicoGUI has a "hotspot" mechanism that makes it easy to use arrow keys, a scroll wheel, or any similar button-like device to select and activate widgets. Unlike the tab system used by most GUIs?, the hotspot system is completely automatic (requires no extra effort from the application programmer) and works in 2 dimensions.

Does PicoGUI require a keyboard?

No. Since keyboard events can be accepted from PicoGUI clients, text entry can be flexible. At the moment we have a very flexible on-screen keyboard called "pgboard". There is a port of the xmerlin handwriting recognition software to PicoGUI, pgmerlin.

What is PicoGUI's history?

PicoGUI officially started development on March 17, 2000 when MicahDowty? wrote the first version of "guwi" over a weekend. But the idea began near the end of the summer of 1999. A phone conversation between MicahDowty? and BrandonSmith? created the KiwiProject?. A couple prototype systems later, it needed a GUI. So, hence was born "guwi". (Temporary name that was kinda like Kiwi + GUI) On April 19, 2000 the project was moved to SourceForge? and given the name PicoGUI. There has been extensive rewrites since then, but PicoGUI's current layout engine is basically the same as it was then.

From March to October of 2000, MicahDowty? was developing PicoGUI alone. The motivation was partially for the Kiwi project, but mostly just for fun. The project got more versatile, and pieces of PicoGUI's new architecture fell into place. In October of 2000, Smartdata joined the PicoGUI team, and this began an entire string of individuals and corporations interested in using and developing PicoGUI.

If I compile a video/input driver into PicoGUI, does it use it automatically?

Usually the answer to this is no. When you compile in a driver, it's made available, but that doesn't mean it's always loaded. By default, pgserver picks one video driver by probing for the first one that loads successfully, and that driver may load additional input drivers only if the video and input drivers are for the same backend. (like sdl and sdlinput, x11 and x11input) All other video drivers expect you to load the input drivers manually. Note that you can have multiple input drivers loaded, but currently only one video driver.

How do I specify input drivers, video drivers, themes, applications, touchscreen calibrators, etc. for pgserver to use?

pgserver has a configuration system used by itself and all drivers, accessible through config files or the command line. Take a look at the output of "pgserver -h" and at the README.configfile in the pgserver directory.

I want to write new language bindings for PicoGUI. Should I create a wrapper around the C client library?

Please don't. PicoGUI's protocol was designed to be easy to write clients for, and it's relatively well documented. If you write a wrapper around the C client library, you'll need to use the C client's constants, and obey all of C's limitations even though you're not using C.

The PicoGUI protocol is language-neutral, and you can utilize the features of your language to make the interface between it and PicoGUI as intuitive as possible. Things like native OOP support, named parameters, operator overloading, and automatic type conversion can all be used to make PicoGUI bindings more intuitive.

If you want to see how this can make a difference, compare the C client library and the Python client library.

Another, smaller, reason to avoid wrapping other client libraries is to reduce dependencies. A user shouldn't need a C client lib if they only use Perl programs for example. This also means that when the C client lib is rewritten (it's been needing a rewrite for a while) your new client lib isn't stuck using an obsolete C binding.

Is PicoGUI suitable for desktop computers?

PicoGUI currently doesn't have enough apps or accelerated video drivers to be useful as an X replacement on the desktop, but in theory PicoGUI should work great on the desktop once more apps and drivers are written. Even though PicoGUI is usually used without overlapping windows, it does support them, and the PicoGUI server is very scalable.

There is already work in progress on a Linux-based OS that uses PicoGUI rootless on X as its native GUI, so PicoGUI apps can run side-by-side with X apps in overlapping windows.

I get a "`FTC_ImageTypeRec?' undeclared" error compiling the Freetype font engine

The freetype font engine currently requires at least version 2.1.3 or the CVS version of freetype.

Does PicoGUI support Internationalisation and Localisation?

Yes. PicoGUI leaves most internationalization tasks up to the client, so applications may use existing libraries like gettext. All text messages used by the PicoGUI server are loadable at runtime, and the server supports Unicode throughout. Currently only basic features of Unicode are supported (no right-to-left text or combining characters yet). PicoGUI's "input filters" mechanism should allow international input methods to be implemented on either the client or the server side.

How does PicoGUI perform for applications that need to update large parts of the screen very often, without using the provided widgets (games, video players...)?

Probably about as well as X or any other GUI that supports shared memory segments. PicoGUI supports a shared memory mechanism very similar to X's MIT-SHM. This allows the picogui server direct access to the app's framebuffer, but still requires a blit to copy that to the real framebuffer. In the future it's planned that picogui will support a faster (but more dangerous) method of allowing the app truly direct access to the framebuffer, similar to DGA.

For video players, picogui doesn't support YUV overlays yet but it should be easy to add, and its on the todo list.

Would PicoGUI be suitable as an embedded GUI inside an OpenGL game?

With PicoGUI's sdlgl driver and support for OpenGL inside themes, it has the potential to be a very powerful and flexable in-game UI. There is work in progress on integrating PicoGUI with a new game engine. Take a look at the "libpgtest" demo in the "apps" directory for an example of how this may work.