FAQ

From Agar

What is Agar?

Agar is a set of software libraries for implementing graphical applications. It is comprised mainly of ag_core, which is a small library that implements Agar's object system, and ag_gui which is the actual GUI system, and includes a number of bundled widgets. Agar is designed to work with multiple graphics backends (or drivers), such as SDL and OpenGL.

The Agar source package also includes some useful graphics-related libraries based on ag_core / ag_gui, such as ag_vg. These libraries are independent from Agar and must be linked explicitely with your application.

Which operating systems does Agar support?

Many - see the portability page and the binary packages available for download. We routinely test Agar on FreeBSD, IRIX, Linux, MacOS Classic, MacOS X, NetBSD, OpenBSD and Windows. It has even been ported to a few game consoles.

Where is the documentation for Agar?

Currently, the main source of Agar documentation is the API Specification (see AG_Intro(3)), which is a series of manual pages in traditional Unix man page format. Since Agar is a library, the API specification is important in that it defines, in detail, the structures and behavior of functions that are guaranteed not to change from one release to another.

The API specification is not structured in any way that would make learning Agar easy. At the time, most people will use the "demos" source code, along with the API specification (which does include some examples), to get acquainted with Agar. This often leads to awkward and improper uses of the API. We are currently working on introductory and general documentation in wiki format.

Why should I choose Agar over toolkit X?

We realize that learning to use a new GUI system can be time-consuming. Whether Agar is right for your application is a question only you can answer. Below are some reasons why we think Agar is useful.

• Agar works under numerous platforms, including embedded systems.
• Agar is released under a BSD license, and so can be used free of charge, for any purpose.
• Agar can use a range of different graphics interfaces, from dumb framebuffers to hardware-accelerated OpenGL rendering. As of Agar-1.4.0, Agar can also interface with window managers to manage multiple "native" windows. Agar drivers to specific embedded device or new platforms can be implemented with ease.
• Agar is designed to be integration-friendly, and to bring the amount of GUI-related code in your application to an absolute minimum. This is achieved using features such as variable "bindings", which delegate the complexity of data access to widget implementations. The Agar design philosophy is to build the GUI around the application, and not the other way around.
• Agar is implemented in C (but can be used from other languages), so the API is simple to learn, the implementation is compact and you don't have to worry about incompatibilities between compilers.
• Agar is modular, object-oriented and extensible. Via the AG_Widget(3) interface, you can create new widgets in C or C++, or inherit from existing Agar widgets as part of your own application or library, without any change needed to Agar. You can even port Agar to a new platform, graphics or window system by registering a new AG_Driver(3) as part of your own application.
• Agar is thread-safe at a fine-grained level. In a multithreaded application, different threads can safely make Agar API calls.
• Agar is skinnable.
• Using vector-based themes (such as the default one), Agar is completely resolution-independent. Most common Agar applications know nothing of pixels.
• Agar has a detailed API specification to ensure changes in new versions do not break backward-compatibility.
• Agar is mature, well-maintained and benefits from strong ongoing development in many areas.

Can I use Agar in a commercial application?

Yes. Agar is released under a BSD license, so it can be incorporated freely into commercial products. There is no requirement of compensation of any kind, but an acknowledgement or a small contribution in return is always appreciated. We can provide commercial support at a reasonable, fixed cost.

Why are the Agar-FOO libraries not in separate distributions?

The extra libraries included in the Agar source distribution (Agar-VG, etc.) can be distributed as separate binary packages from Agar and you have to explicitely link your application against them in order to use them. We prefer to keep those libraries in the same source package since they are generic and maintained by the same team. They are also required by some bundled utilities such as agarpaint.

It is simple to use Agar in Windows?

It is a simple as using a library under Windows can be. Agar can be easily integrated into a variety of environments, such as Visual Studio, Cygwin and MSYS. See the download page for precompiled binary packages, and follow the "NOTES" links for installation guides.

Is agar skinnable?

Yes, and custom themes can be distributed as part of your application. See AG_Style(3) for more details.

Using Agar on game consoles

How do I use Agar on the Playstation2?

Assuming you have the PS2Linux kit installed, you should be able to install the Agar Linux/mipsel binary package. This package has been tested with the North American PS2Linux kit (1.0).

How do I use Agar on the Nintendo GameCube/Wii?

There are a couple of ways to do this. By far the easiest solution is to purchase a Datel "SD Media Launcher" kit (available from Divineo and other places), which includes a disc, memory card adapter and a SD card.

As of Agar-1.3, you must first install and boot GameCube Linux. This requires a LAN adapter and a Unix machine to act as a NFS server. Once Linux is booted, you can install Agar from a Linux/powerpc binary package. We are planning on adding standalone GameCube/Wii support. This will allow you to create standalone .dol executables that do not depend on Linux.

Can I use Agar from C++?

Yes, Agar is safe to use from C++, and you also do not need to enclose the Agar includes in "extern C".

Can I render widgets and process events in two different threads?

Yes.

Which OpenGL versions does Agar work with?

Agar works with OpenGL 1.1 and up. It should work with OpenGL ES 1.1 and up as well.

Can I make OpenGL calls anywhere in my application?

If you are using your own event loop, this is under your control and you can always assume that Agar will make OpenGL calls from only AG_InitVideo(), AG_WidgetDraw() and AG_ProcessEvent() for events of type VIDEORESIZE and VIDEOEXPOSE.

If you are using the default AG_EventLoop(), you must not make any OpenGL call in any context other than the draw() operation of a widget. This applies to all OpenGL calls, including texture management routines. Creating or deleting textures from an event handler or the init() operation of a widget, for example, would break thread safety under OpenGL mode. The AG_WidgetMapSurface() and AG_WidgetReplaceSurface() functions can be used anywhere, but Agar will internally defer the actual texture operations involved until AG_WidgetBlitFrom() is used on the surface.

The AG_GLView(3) widget is intended as a general OpenGL context. It does nothing special other than automatically loading and saving the projection/modelview matrices of your choice.

Can I use Agar with an already initialized SDL/OpenGL display?

Yes, simply use AG_InitVideoSDL() instead of AG_InitVideo(). This function takes a pointer to your existing display SDL_Surface. Note that if your display surface has the SDL_OPENGL or SDL_OPENGLBLIT flag set, Agar will render itself using GL primitives.

How can I render surfaces / draw images?

There are many ways to do this. Probably the simplest is using the AG_Pixmap widget. This is optional but if you simply call AG_PixmapUpdateSurface() every time the surface changes, your application will be able to work under OpenGL.

If you need to do things like capture mouse events, writing a custom widget would be best (in your widget code, you would just use AG_WidgetMapSurface() followed by AG_WidgetBlitSurface() to draw the surface).

Custom event loops

When should I use a custom event loop?

Custom event loops are useful when integrating an Agar GUI in an existing application, or in specific situations where the default event loop is not suitable.

As of Agar-1.4.0, custom event loops are provided with the AG_GetNextEvent() and AG_ProcessEvent() functions, which allow low-level events (e.g., mouse motion, keypress events) to be processed in a specific way by the application.

I'm using a custom event loop from an OpenGL application and the Y-coordinates are inverted or the scaling is incorrect, why?

Most likely your application is overriding the projection matrix set by Agar on initialization. If you have no other options, prior to rendering the Agar windows, you can always reset the expected projection matrix using:

glOrtho(0, agView->w, agView->h, 0, -1.0, 1.0);

Why is my application still using CPU while idle?

Most likely you are using the "sdlfb" graphics driver. Inevitably, the rendering of GUI elements under a dumb framebuffer has to be done entirely by the CPU. Assuming you have modern hardware with a hardware-accelerated OpenGL available, you should use one of the OpenGL drivers instead. Using an OpenGL driver, the CPU usage will be minimal as the rendering of GUI elements occurs in the graphics hardware.