.\"
.\" Copyright (c) 2001-2024 Julien Nadeau Carriere <vedge@csoft.net>
.\" 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 December 21, 2022
.Dt AG_INTRO 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Intro
.Nd agar introduction
.Sh DESCRIPTION
Agar is a cross-platform GUI system and framework.
It provides a programming platform and a standard toolkit of widgets from
which graphical applications can be built.
.Sh AGAR-CORE
The
.Em ag_core
library is Agar's non-graphical platform and utility library.
It implements the base object system, events / virtual functions and timers.
It provides cross-platform interfaces to OS services such as
filesystems, kernel-based events, timers and threads.
To use this library alone (without GUI), link against
.Sq agar-core-config --libs .
.Pp
.\" SYNC WITH AG_Core(3) "SEE ALSO"
.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
Data sources and serialization.
.It Xr AG_Db 3
Generic database access methods.
.It Xr AG_DSO 3
Dynamic linker interface.
.It Xr AG_Error 3
Error handling and error-checking memory allocation.
.It Xr AG_Event 3
Event handlers / virtual functions.
.It Xr AG_EventLoop 3
Low-level event loop.
Event sources and sinks.
.It Xr AG_Execute 3
File execution interface.
.It Xr AG_File 3
File access routines.
.It Xr AG_Limits 3
Limit constants.
.It Xr AG_Object 3
The Agar object system.
.It Xr AG_String 3
C string specific functions.
.It Xr AG_TextElement 3
Multilanguage dynamic text buffer.
.It Xr AG_Threads 3
Threads interface.
.It Xr AG_Timer 3
The Agar timer facility.
.It Xr AG_Time 3
Monotonically-increasing time sources.
.It Xr AG_User 3
User account information access.
.It Xr AG_Variable 3
Agar object variables.
.It Xr AG_Version 3
Data file versioning.
.El
.Sh AGAR-GUI: BASE SYSTEM
The
.Em ag_gui
library includes the base Agar GUI system and its standard widget toolkit.
To use it, link against
.Sq agar-config --libs .
.Pp
.Bl -tag -width "AG_WidgetPrimitives(3) " -compact
.It Xr AG_AlphaFn 3
Alpha blending functions.
.It Xr AG_Color 3
Color structure.
.It Xr AG_Cursor 3
Cursor configuration.
.It Xr AG_Driver 3
Driver (backend) interface.
.It Xr AG_DriverSw 3
Driver interface for single-window drivers.
.It Xr AG_DriverMw 3
Driver interface for multi-window drivers.
.It Xr AG_GlobalKeys 3
Application-wide keyboard shortcuts.
.It Xr AG_GL 3
OpenGL-specific functions.
.It Xr AG_GuiDebugger 3
GUI debugging tool.
.It Xr AG_InitGraphics 3
Agar GUI initialization.
.It Xr AG_Keyboard 3
Interface to keyboard status.
.It Xr AG_KeySym 3
Keyboard key definitions.
.It Xr AG_KeyMod 3
Modifier keys definitions.
.It Xr AG_MouseButton 3
Mouse button definitions.
.It Xr AG_StyleSheet 3
Agar's version of cascading style sheets.
.It Xr AG_Surface 3
Graphics surfaces.
.It Xr AG_Text 3
Typography; interface to the font engine.
.It Xr AG_Units 3
Conversion between different unit systems.
.It Xr AG_Widget 3
The base class for Agar widgets (and windows).
.It Xr AG_WidgetPrimitives 3
Rendering primitives for GUI elements.
.It Xr AG_Window 3
The base container for Agar widgets.
.El
.Sh AGAR-GUI: STANDARD WIDGETS
Standard widgets in in
.Em ag_gui
(unless built with "--disable-widgets").
.Pp
.Bl -tag -width "AG_ObjectSelector(3) " -compact
.It Xr AG_Box 3
Horizontal/vertical widget container.
.It Xr AG_Button 3
Push-button widget.
.It Xr AG_Checkbox 3
Checkbox widget.
.It Xr AG_Combo 3
Canned text input/drop-down menu widget.
.It Xr AG_Console 3
Scrollable text console widget.
.It Xr AG_DirDlg 3
Directory selection widget.
.It Xr AG_Editable 3
The Agar text editor (plain editable field).
.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_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
Spinbutton widget (for integers or floats).
.\" .It Xr AG_ObjectSelector 3
.\" Selector for
.\" .Xr AG_Object 3
.\" trees.
.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).
.It Xr AG_Scrollbar 3
Scrollbar (integer or floating-point).
.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).
.It Xr AG_Socket 3
Placeholder for drag-and-droppable
.Xr AG_Icon 3 .
.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
The Agar text editor (an
.Ft AG_Editable
in a box).
.It Xr AG_Tlist 3
Linearized tree / list box widget.
.It Xr AG_Toolbar 3
Specialized button container for toolbars.
.It Xr AG_UCombo 3
Single-button variant of
.Xr AG_Combo 3 .
.El
.Sh AGAR-MATH
The
.Em ag_math
library is a general-purpose math library which extends Agar with new widgets
and support for linear algebra / geometry types.
To use this library, link against
.Sq agar-math-config --libs .
.Pp
.Bl -tag -width "M_Quaternion(3) " -compact
.It Xr M_Matrix 3
Matrix operations.
Provides optimized methods for sparse matrices
(common in scientific applications)
as well as 4x4 matrices
(common 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.
.It Xr M_Sort 3
Sort algorithms (qsort, heapsort, mergesort, radixsort)
.It Xr M_VectorZ 3
Vectors with signed integer valued elements.
.It Xr M_String 3
Math-specific extensions to the
.Xr AG_Printf 3
engine.
.It Xr M_Line 3
Lines, half-lines and line segments.
.It Xr M_Matview 3
Visualization widget for
.Xr M_Matrix 3 .
.It Xr M_Plane 3
Routines related to planes in R^3.
.It Xr M_Plotter 3
General-purpose plotting widget (displays sets of
.Ft M_Real ,
.Ft M_Vector
and
.Ft M_Complex
elements).
.It Xr M_PointSet 3
Operations on sets of points (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
Vectors (optimized R^2, R^3 and R^4 or general R^n).
.El
.Sh AGAR-NET
The
.Em ag_net
library provides network access methods and implements a modular HTTP/1.1
application server.
To use this library, link against
.Sq agar-net-config --libs .
.Pp
.Bl -tag -width "AG_Net (3) " -compact
.It Xr AG_Net 3
Interface to network services.
.It Xr AG_Web 3
HTTP/1.1 application server.
.El
.Sh AGAR-SG
The
.Em ag_sg
library (beta) provides a basic 3D engine.
It implements 3D scene-graph, rendering and geometry methods.
To use this library, link against
.Sq agar-sg-config --libs .
.Pp
.Bl -tag -width "SG_CgProgram(3) " -compact
.It Xr SG 3
Base scene graph object.
.It Xr SG_Image 3
Textured polygon generated from an image surface.
.It Xr SG_Camera 3
Viewpoint in scene (tied to the
.Xr SG_View 3
widget).
.It Xr SG_CgProgram 3
Vertex/fragment program in the Cg language.
.It Xr SG_Circle 3
Circle (reference geometry).
.It Xr SG_Geom 3
Base class for reference geometry objects.
.It Xr SG_Light 3
Light source.
.It Xr SG_Node 3
Base class for all elements of a
.Xr SG 3
scene.
.It Xr SG_Object 3
Base class for polyhedral objects (as brep).
.It Xr SG_Plane 3
Plane (reference geometry).
.It Xr SG_Point 3
Single point (reference geometry).
.It Xr SG_Polygon 3
Polygon (reference geometry).
.It Xr SG_PolyBall 3
Sphere (as polyhedral approximation).
.It Xr SG_PolyBox 3
Rectangular box (as polyhedron).
.It Xr SG_Program 3
Base class for vertex or fragment programs.
.It Xr SG_Rectangle 3
Rectangle (reference geometry).
.It Xr SG_Sphere 3
Sphere (reference geometry).
.It Xr SG_Texture 3
Texture compiled from a set of surfaces.
.It Xr SG_Triangle 3
Triangle (reference geometry).
.It Xr SG_View 3
Agar visualization and editor widget for
.Xr SG 3
scenes.
.It Xr SG_Voxel 3
Voxel object.
.El
.Sh AGAR-SK
The
.Em ag_sk
library (beta) implements dimensioned 2D sketches with constraint solving
through degree-of-freedom analysis.
Sketches contain sets of metric relations (i.e., distances, angles)
and logical relations (i.e., coincidence, parallelism, tangency).
To use this library, link against
.Sq agar-sk-config --libs .
.Pp
.Bl -tag -width "SK_View(3) " -compact
.It Xr SK 3
Base sketch object.
.It Xr SK_View 3
Agar visualization widget for sketch objects.
.El
.Sh AGAR-AU
The
.Em ag_au
library (beta) provides a sound interface extends
.Em ag_gui
with widgets useful in audio applications such as waveform visualizers.
To use this library, link against
.Sq agar-au-config --libs .
.Pp
.Bl -tag -width "AU_DevOut(3) " -compact
.It Xr AU 3
Audio library initialization.
.It Xr AU_Wave 3
Structure containing an audio stream.
.It Xr AU_DevOut 3
Interface to audio output device.
.El
.Sh AGAR-MAP
The
.Em ag_map
library (beta) implements a simple and extensible 2D/3D tile engine.
To use this library, link against
.Sq agar-map-config --libs .
.Pp
.Bl -tag -width "RG_Tileview(3) " -compact
.It Xr MAP 3
Base map object.
.It Xr MAP_Actor 3
Map object rendered dynamically.
.It Xr MAP_View 3
Visualization and edition widget.
.It Xr RG 3
Feature-based 2D pixel graphics.
.It Xr RG_Feature 3
Base feature framework.
.It Xr RG_Pixmap 3
A pixmap image element.
.It Xr RG_Sketch 3
A vector sketch element.
.It Xr RG_Texture 3
A texture element.
.It Xr RG_Tile 3
Base tile element.
.It Xr RG_Tileview 3
Edition and visualization widget.
.El
.Sh AGAR-VG
The
.Em ag_vg
library implements basic 2D vector graphics display.
It includes an editor tool framework.
Geometrical placement of elements is determined by linear transformations
using floating-point methods.
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
Display and edition widget.
.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 COMMON MANUAL SECTIONS
Manual pages are provided for most Agar object classes.
Some sections are standard throughout the documentation:
.Bl -tag -width "INHERITANCE HIERARCHY "
.It INHERITANCE HIERARCHY
List of inherited parent classes (see
.Xr AG_Object 3
for details on inheritance).
.It EVENTS
The list of events defined (or raised) by this object (see
.Xr AG_Event 3
for details on events).
.It STRUCTURE DATA
List of public structure members which are safe to access directly.
Multithreaded applications must use
.Xr AG_ObjectLock 3
prior to accessing this data (although in some contexts, such as inside event
handler routines, objects can be presumed locked; see
.Xr AG_Threads 3
for details).
.El
.Sh SEE ALSO
.Bl -tag -compact
.It Lk https://libAgar.org/ Agar Website
.It Lk https://patreon.com/libagar Agar Patreon
.It Lk https://github.com/JulNadeauCA/libagar Agar GitHub
.El