Agar FAQ

This FAQ is supplemental to the Agar API documentation, and it covers Agar version 1.3.2. It is likely that parts of this FAQ do not reflect changes in the latest development version.

What is Agar?

Agar is a set of software libraries for graphical applications. It is comprised of ag_core, which is a small library that implements Agar's object system, and ag_gui which is the actual GUI library. 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 VG. These libraries are independent from Agar and must be linked explicitely.

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.

Is agar skinnable?

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

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 different graphics APIs (or drivers). As of release 1.3, both SDL and OpenGL are supported. SDL is highly portable and well-maintained. OpenGL, where available, allows your application to offload most graphics processing to the graphics hardware, reducing its CPU utilization by orders of magnitude. Agar-1.4 will feature even more graphics drivers.
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. It is actually common practice to ifdef all GUI-related code in Agar applications where the GUI is optional.
Agar is implemented in C (but can be used from other languages), so the API is simple to learn, the implementation is very compact and you don't have to worry about incompatibilities between compilers.
Agar is object-oriented and extensible. 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.
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 Agar applications know nothing of pixels.
Agar has detailed documentation, which we put a lot of effort into maintaining.
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, Agar-MAP, 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, graphics-related and maintained by the same team. They are also required by the bundled agarpaint tool, which is useful to Agar developers.

It is simple to use Agar in Windows?

Yes, 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.

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 currently working on standalone GameCube/Wii support. This will allow you to create standalone .dol executables that do not depend on Linux.

How does inheritance work if I use C?

See the the "objsystem" demo ( http://dev.hypertriton.com/agar/trunk/demos/objsystem ) for an example of the Agar object system in C. The key is the use of structure packing and casts. If this is done correctly along with a robust object system, it results in very clean, compact code.

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". A class-based C++ interface is currently under development.

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

Yes, but we have not tested this case extensively.

Can I make OpenGL calls anywhere?

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 some 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 defer the actual texture operations involved until AG_WidgetBlitFrom() is used on the surface.

The AG_GLView 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).

When should I use a custom event loop?

Custom event loops are only really useful in situations where you need to generate "forged" input device events, or control the display's refresh rate in a specific way. See this tutorial for details on how to do this.

A good example would be a DVR application, which would require the display to be synchronized with the video input. In such an application, you could also generate Agar events from a remote control via LIRC. If your DVR application is designed for specialized hardware, you could use a custom event loop to synchronize the display with some hardware interrupt. These are the kinds of specialized situations where the default event loop would be inefficient.

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