.\" Copyright (c) 2001-2008 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd NOVEMBER 26, 2001
.Dt AG_INTRO 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_Intro
.Nd agar introduction
.Sh DESCRIPTION
Agar is a graphical application toolkit.
It provides all types of graphical applications, written in different languages,
with consistent interfaces across a wide array of platforms.
.Pp
This document summarizes the various interfaces provided by the standard
libraries included in the official Agar source distribution (such as Agar-Core,
Agar-GUI, etc).
These libraries share the same version number and release cycle, but they are
separate and can be packaged and distributed independently.
.Pp
.Sh USING THE AGAR DOCUMENTATION
The Agar documentation follows the following important conventions:
.Bl -enum
.It
The return value for functions returning
.Ft int ,
unless otherwise documented, represents an error code (where 0 = success,
-1 = failure).
On failure, the error message can be retrieved using
.Xr AG_GetError 3 .
.It
When Agar is compiled with threads support, functions are thread-safe
unless documented otherwise (see
.Dq CONVENTIONS
section of
.Xr AG_Threads 3
for important details related to thread safety).
.El
.Pp
There is generally one manual page per Agar object class in the Agar API
documentation.
A number of manual page sections are standard throughout the documentation,
this includes:
.Bl -tag -width "INHERITANCE HIERARCHY "
.It INHERITANCE HIERARCHY
List of parent (inherited) classes.
See
.Xr AG_Object 3
for details on inheritance with the Agar object system.
.It EVENTS
List of events defined by this object (and optionally, a list
of events potentially raised by this object).
See
.Xr AG_Event 3
for details on Agar events.
.It STRUCTURE DATA
List of public structure members which are safe to access directly (in the
specified way).
Function interfaces are always available so developers who prefer to use them
exclusively can ignore these sections.
.Pp
Note: Multithreaded applications must use
.Xr AG_ObjectLock 3
prior to accessing this data (although the object can be assumed locked
in some contexts, see
.Xr AG_Event 3
for details).
.El
.Sh AGAR-CORE
Agar-Core implements the
.Xr AG_Object 3
object system which is used extensively by all other Agar libraries.
It also provides cross-platform interfaces to operating system services
(e.g., filesystems, network services, threads).
.Pp
To use this library, link against
.Sq agar-config --libs
(non-graphical applications can also link against
.Sq agar-core-config --libs
to avoid the GUI library).
.Pp
.Bl -tag -width "AG_DataSource(3) " -compact
.It Xr AG_Config 3
Manage Agar configuration settings.
.It Xr AG_Core 3
Core Agar library initialization.
.It Xr AG_DataSource 3
Generic interface to different data sources.
.It Xr AG_DSO 3
Cross-platform interface to dynamic linkers.
.It Xr AG_Error 3
Error handling in Agar.
.It Xr AG_File 3
Portable interface to filesystems.
.It Xr AG_Object 3
The Agar object system.
.It Xr AG_Event 3
Event handling for objects.
.It Xr AG_Limits 3
Interface to platform-dependent limits.
.It Xr AG_Threads 3
Portable threads interface.
.It Xr AG_Timeout 3
Timing-related routines.
.It Xr AG_Variable 3
Primitiive data variables and bindings.
.It Xr AG_Version 3
Datafile versioning functions.
.El
.Sh AGAR-GUI
Agar-GUI implements a standard widget set and a built-in window system.
It is implemented in a fashion independent of the underlying graphics API
(i.e., direct-video, OpenGL), and is designed to provide the highest
performance and efficiency achievable with any given graphics system.
.Pp
To use this library, link against
.Sq agar-config --libs .
.Pp
.Bl -tag -width "AG_Window(3) " -compact
.It Xr AG_Colors 3
Color scheme interface.
.It Xr AG_Style 3
The high-level themeing API.
.It Xr AG_Surface 3
Graphics surfaces.
.It Xr AG_Text 3
Interface to font engine (i.e., FreeType or bitmap fonts).
.It Xr AG_Units 3
Conversion between different unit systems.
.It Xr AG_View 3
Low-level interface to the graphics display.
.It Xr AG_Widget 3
Generic widget interface.
.It Xr AG_Window 3
Basic window widget; interface to built-in window manager.
.El
.Sh AGAR-GUI: STANDARD WIDGETS
The standard Agar widget set provides the basic GUI functionality useful to
the widest range of applications.
Note that the implementation of more specialized and application-specific
widgets (made simple by the
.Xr AG_Object 3
interface) is encouraged, as demonstrated by the other standard Agar libraries
which include a few of them.
.Pp
.Bl -tag -width "AG_ObjectSelector(3) " -compact
.It Xr AG_Box 3
Horizontal/vertical widget container.
.It Xr AG_Button 3
Generic push-button widget (boolean bindings).
.It Xr AG_Checkbox 3
Generic checkbox widget (boolean bindings).
.It Xr AG_Combo 3
Text input/drop-down menu widget.
.It Xr AG_Console 3
Scrollable text console widget.
.It Xr AG_Editable 3
Low-level text edition widget (string bindings, UTF-8 supported).
.It Xr AG_FileDlg 3
File selection widget.
.It Xr AG_Fixed 3
Container for fixed position/geometry widgets.
.It Xr AG_FontSelector 3
Font selection widget.
.It Xr AG_GLView 3
Low-level OpenGL context widget.
.It Xr AG_Graph 3
Graph display widget.
.It Xr AG_FixedPlotter 3
Plotter for integral values.
.It Xr AG_HBox 3
Alternate interface to
.Xr AG_Box 3 .
.It Xr AG_HSVPal 3
Hue/saturation/value color picker widget.
.It Xr AG_Icon 3
Drag-and-droppable object that can be inserted into
.Xr AG_Socket 3
widgets.
.It Xr AG_Label 3
Display a string of text (static or polled).
.It Xr AG_MPane 3
Standard single, dual, triple and quad paned view.
.It Xr AG_Menu 3
Menu widget.
.It Xr AG_Notebook 3
Notebook widget.
.It Xr AG_Numerical 3
Numerical input / spinbutton widget for floating-point and integer
values.
.\" .It Xr AG_ObjectSelector 3
.\" Selector for
.\" .Xr AG_Object 3
.\" trees.
.It Xr AG_Palette 3
Edit a RGB color value (Uint32/AG_PixelFormat bindings). Obsoleted
by
.Xr AG_HSVPal 3 .
.It Xr AG_Pane 3
Dual paned view.
.It Xr AG_Pixmap 3
Displays arbitrary surfaces.
.It Xr AG_ProgressBar 3
Progress bar widget.
.It Xr AG_Radio 3
Simple radio group widget (integer bindings).
.It Xr AG_Scrollbar 3
Scrollbar (integer or floating-point bindings).
.It Xr AG_Scrollview 3
Scrollable view.
.It Xr AG_Separator 3
Cosmetic separator widget.
.It Xr AG_Slider 3
Slider control (integer or floating-point bindings).
.It Xr AG_Socket 3
Placeholder for drag-and-droppable
.Xr AG_Icon 3
objects.
.It Xr AG_Statusbar 3
Specialized statusbar widget.
.It Xr AG_Table 3
Table display widget.
.It Xr AG_Treetbl 3
Tree-based table display widget.
.It Xr AG_Textbox 3
Text edition widget (string bindings, UTF-8 supported).
.It Xr AG_Tlist 3
Tree/list widget (either static or polled).
.It Xr AG_Toolbar 3
Specialized button container for toolbars.
.It Xr AG_UCombo 3
Variant of
.Xr AG_Combo 3
which displays a button instead of a text input.
.It Xr AG_VBox 3
Alternate interface to
.Xr AG_Box 3 .
.El
.Pp
.Sh AGAR-VG
Agar-VG is a simple 2D vector graphics library which allows developers
to specify hierarchical sketches consisting of elements such as lines, curves
and text.
It uses linear transformations to define the placement of geometrical
entities, which the best approach for most applications.
.Pp
Following the same design philosophy as Agar-GUI, Agar-VG only provides the
entity classes (e.g., lines, arcs) useful to the widest range of applications,
and allows specialized and application-specific entities to be implemented
easily in separate libraries.
For specialized applications such as CAD systems, the placement of entities
might be best described through geometrical constraints (e.g., distances and
angles) as opposed to linear transformations.
This functionality is implemented in the FreeSG library (see
.Dq FREESG ) .
.Pp
To use this library, link against
.Sq agar-vg-config --libs .
.Pp
.Bl -tag -width "VG_Polygon(3) " -compact
.It Xr VG 3
Vector drawing object.
.It Xr VG_View 3
Agar widget for visualization and edition of drawings.
.It Xr VG_Arc 3
Arc entity.
.It Xr VG_Circle 3
Circle entity.
.It Xr VG_Line 3
Line entity.
.It Xr VG_Polygon 3
Polygon entity.
.It Xr VG_Text 3
Text entity.
.El
.Sh AGAR-RG
Agar-RG is a library for generating and manipulating raster graphics (either
static or animated) by compositing a set of graphical elements.
It implements a "smart" image format which allows directives, transformations
and instancing of graphical elements.
.Pp
To use this library, link against
.Sq agar-rg-config --libs .
.Pp
.Bl -tag -width "RG_Animview (3) " -compact
.It Xr RG_Tileset 3
Package for graphics, animations and textures.
.It Xr RG_Tile 3
Surface generated from a set of instructions.
.It Xr RG_Texture 3
Tile reference with texturing settings.
.It Xr RG_Anim 3
Animation generated from a set of instructions.
.It Xr RG_Pixmap 3
Graphical surface used internally.
.It Xr RG_Feature 3
Generic graphical operation framework.
.It Xr RG_Tileview 3
Widget for graphics edition, generic tool framework with undo.
.El
.Sh AGAR-MATH
Agar-Math is a general-purpose math library focused on providing consistent
structures and highly optimized routines.
In addition to linear algebra, Agar-Math also provides useful computational
geometry structures and methods (e.g., intersections, tesselations), portable
complex-number/quaternion routines and some useful Agar-GUI widgets and
extensions.
.Pp
To use this library, link against
.Sq agar-math-config --libs .
.Pp
.Bl -tag -width "M_Quaternion(3) " -compact
.It Xr M_Intro 3
Math library initialization and primitive types.
.It Xr M_Matrix 3
Routines specific to matrices.
This includes general m-by-n matrices (frequently encountered in scientific
applications and usually solved with sparse-matrix optimizations),
as well as a specialized interface for 4x4 matrices (usually countered in
computer graphics).
.It Xr M_Circle 3
Circles in R^2 and R^3.
.It Xr M_Color 3
Mapping between different color spaces.
.It Xr M_Complex 3
Complex-number arithmetic not reliant on compiler extensions.
.It Xr M_Coordinates 3
Mapping between different coordinate systems.
.It Xr M_Sort 3
Sorting algorithms (qsort, heapsort, mergesort, radixsort)
.It Xr M_IntVector 3
Vector operations for vectors with integer elements.
.It Xr M_Line 3
Routines related to lines, half-lines and line segments.
.It Xr M_Matview 3
Agar-GUI widget for viewing the contents of
.Xr M_Matrix 3
objects numerically or graphically.
.It Xr M_Plane 3
Routines related to planes in R^3.
.It Xr M_Plotter 3
General-purpose plotting widget for Agar-GUI, with support for
.Ft M_Real ,
.Ft M_Vector
and
.Ft M_Complex
types.
.It Xr M_PointSet 3
Set of points and related operations (e.g., convex hull).
.It Xr M_Polygon 3
Operations related to polygons in R^2 and R^3.
.It Xr M_Quaternion 3
Basic quaternion arithmetic.
.It Xr M_Rectangle 3
Routines specific to rectangles in R^2 and R^3.
.It Xr M_Triangle 3
Routines specific to triangles in R^2 and R^3.
.It Xr M_Vector 3
Basic linear algebra routines specific to vectors.
In addition to vectors in R^n, specialized operations are provided for
vectors in R^2, R^3 and R^4.
.El
.Sh FREESG
The FreeSG library implements scene-graphs for 2D and 3D applications.
It is a general-purpose library used in scientific/engineering applications,
visualization applications and games.
.Pp
It differs from most other scene-graph libraries in the way elements are
related to each other in a scene.
Instead of explicit matrix transformations, elements can be related to each
other in terms of geometrical constraints (such as distances, coincidences,
angles).
In addition to vector-based scenes, FreeSG also includes a 2D tiling library
aimed at isometric games, platform games and scrollers.
.Pp
FreeSG is not part of the Agar source distribution, but it is built on top
of the Agar library, and adds a few Agar widgets for visualization and
edition purposes.
See: http://freesg.org/ for more details.