Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AG_INTRO(3)		 BSD Library Functions Manual		   AG_INTRO(3)

     AG_Intro -- agar introduction

     Agar is a graphical application toolkit.  It provides all types of	graph-
     ical applications,	written	in different languages,	with consistent	inter-
     faces across a wide array of platforms.

     This document summarizes the various interfaces provided by the standard
     libraries included	in the official	Agar source distribution (such as
     ag_core, ag_gui, etc.)  These libraries share the same version number and
     release cycle, but	they are separate and can be packaged and distributed

     The Agar API Reference is intended	as a detailed specification explaining
     Agar's functions and structures in	sufficient detail.  To avoid the con-
     tent becoming repetitive, the API Reference uses a	number of important
     conventions regarding error handling and thread-safety:

     o	 The return value for functions	returning int, unless otherwise	docu-
	 mented, represents an error code, where 0 indicates success and -1
	 indicates failure.  On	failure, an error message string can be	re-
	 trieved using AG_GetError(3).

     o	 Some functions	have variants differing	only in	argument format.  For
	 example, AG_LabelNew(3) accepts a format string, and AG_LabelNewS(3)
	 accepts a plain C string.  Since the difference is shown in function
	 prototype, it is customary to omit mentioning those variants in the
	 following paragraph describing	the function.

     o	 Some functions	have variants differing	only in	error-handling style.
	 Those may also	be omitted from	the description	paragraph.  For	exam-
	 ple, AG_MutexInit(3) has no return value.  If the function fails, an
	 AG_FatalError(3) is raised.  The AG_MutexTryInit variant, however,
	 returns 0 on success or -1 on failure.

     o	 When Agar is compiled with threads support, Agar functions are
	 thread-safe (free-threaded), unless documented	otherwise (see
	 "CONVENTIONS" section of AG_Threads(3)	for important details related
	 to thread safety).

     There is generally	one manual page	per Agar object	class.	A number of
     manual page sections are standard throughout the documentation, this in-

     INHERITANCE HIERARCHY   List of parent (inherited)	classes.  See
			     AG_Object(3) for details on inheritance with the
			     Agar object system.

     EVENTS		     List of events defined by this object (and	op-
			     tionally, a list of events	potentially raised by
			     this object).  See	AG_Event(3) for	details	on
			     Agar events.

     STRUCTURE DATA	     List of public structure members which are	safe
			     to	access directly	(in the	specified way).	 Mul-
			     tithreaded	applications must use AG_ObjectLock(3)
			     prior to accessing	this data (although in some
			     contexts, such as inside event handler routines,
			     objects can be presumed locked; see AG_Threads(3)
			     for details).

     Agar's general utility library is named ag_core.  It implements the
     AG_Object(3) object system	which is used extensively by all other Agar
     libraries.	 It also provides cross-platform interfaces to operating sys-
     tem services (e.g., filesystems, network services,	threads).

     To	use this library, link against `agar-config --libs' (non-graphical ap-
     plications	can also link against `agar-core-config	--libs'	to avoid the
     GUI library).

     AG_Config(3)	Manage Agar configuration settings.
     AG_Core(3)		Core Agar library initialization.
     AG_DataSource(3)	Generic	interface to different data sources.
     AG_Db(3)		Database access	methods.
     AG_DSO(3)		Cross-platform interface to dynamic linkers.
     AG_Error(3)	Error handling in Agar.
     AG_Event(3)	Virtual	functions (at the Agar object level).
     AG_EventLoop(3)	Main application event loop.  General event sources
			and sinks.
     AG_Execute(3)	Cross-platform interface to program execution.
     AG_File(3)		Portable interface to filesystems.
     AG_Limits(3)	Interface to platform-dependent	limits.
     AG_Net(3)		Interface to network I/O facilities.
     AG_Object(3)	The Agar object	system.
     AG_String(3)	Functions for manipulating C strings.
     AG_TextElement(3)	Dynamically-allocated multilanguage text buffer.
     AG_Threads(3)	Portable threads interface.
     AG_Timer(3)	Timer facility.
     AG_Time(3)		Interface to time sources.
     AG_User(3)		Cross-platform interface to user accounts.
     AG_Variable(3)	Primitive data variables and bindings.
     AG_Version(3)	Datafile versioning functions.

     The ag_gui	library	implements the Agar GUI	system.	 It also includes a
     set of standard, built-in widgets.	 The Agar GUI 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 effi-
     ciency achievable with any	given graphics system.

     To	use this library, link against `agar-config --libs'.

     AG_Anim(3)		      Animated graphics	surfaces.
     AG_BlendFn(3)	      Pixel blending functions.
     AG_Color(3)	      Color structure.
     AG_Cursor(3)	      Cursor configuration.
     AG_Driver(3)	      Driver (backend) interface.
     AG_GlobalKeys(3)	      Application-wide keyboard	shortcuts.
     AG_GL(3)		      OpenGL-specific functions.
     AG_GuiDebugger(3)	      GUI debugging tool.
     AG_KeySym(3)	      Keyboard key definitions.
     AG_KeyMod(3)	      Keyboard modifier	definitions.
     AG_MouseButton(3)	      Mouse button definitions.
     AG_StyleSheet(3)	      Agar's version of	cascading style	sheets.
     AG_Surface(3)	      Graphics surfaces.
     AG_Text(3)		      Interface	to font	engine / text rendering	facil-
     AG_Units(3)	      Conversion between different unit	systems.
     AG_Widget(3)	      Generic widget interface.
     AG_WidgetPrimitives(3)   Widget rendering primitives.
     AG_Window(3)	      Basic window / window manager interface.

     The standard Agar widget set provides the basic GUI functionality useful
     to	the widest range of applications.  Developers are encouraged to	imple-
     ment more specialized and application-specific widgets (this is made sim-
     ple by use	of the AG_Object(3) system).

     AG_Box(3)		    Horizontal/vertical	widget container.
     AG_Button(3)	    Push-button	widget.
     AG_Checkbox(3)	    Checkbox widget.
     AG_Combo(3)	    Canned text	input/drop-down	menu widget.
     AG_Console(3)	    Scrollable text console widget.
     AG_DirDlg(3)	    Directory selection	widget.
     AG_Editable(3)	    Low-level text edition widget (string bindings,
			    UTF-8 supported).
     AG_FileDlg(3)	    File selection widget.
     AG_Fixed(3)	    Container for fixed	position/geometry widgets.
     AG_FontSelector(3)	    Font selection widget.
     AG_GLView(3)	    Low-level OpenGL context widget.
     AG_Graph(3)	    Graph display widget.
     AG_FixedPlotter(3)	    Plotter for	integral values.
     AG_HBox(3)		    Alternate interface	to AG_Box(3).
     AG_HSVPal(3)	    Hue/saturation/value color picker widget.
     AG_Icon(3)		    Drag-and-droppable object that can be inserted
			    into AG_Socket(3) widgets.
     AG_Label(3)	    Display a string of	text (static or	polled).
     AG_MPane(3)	    Standard single, dual, triple and quad paned view.
     AG_Menu(3)		    Menu widget.
     AG_Notebook(3)	    Notebook widget.
     AG_Numerical(3)	    Numerical input / spinbutton widget	for floating-
			    point and integer values.
     AG_Pane(3)		    Dual paned view.
     AG_Pixmap(3)	    Displays arbitrary surfaces.
     AG_ProgressBar(3)	    Progress bar widget.
     AG_Radio(3)	    Simple radio group widget (integer bindings).
     AG_Scrollbar(3)	    Scrollbar (integer or floating-point bindings).
     AG_Scrollview(3)	    Scrollable view.
     AG_Separator(3)	    Cosmetic separator widget.
     AG_Slider(3)	    Slider control (integer or floating-point bind-
     AG_Socket(3)	    Placeholder	for drag-and-droppable AG_Icon(3) ob-
     AG_Statusbar(3)	    Specialized	statusbar widget.
     AG_Table(3)	    Table display widget.
     AG_Treetbl(3)	    Tree-based table display widget.
     AG_Textbox(3)	    Text edition widget	(string	bindings, UTF-8	sup-
     AG_Tlist(3)	    Tree/list widget (either static or polled).
     AG_Toolbar(3)	    Specialized	button container for toolbars.
     AG_UCombo(3)	    Variant of AG_Combo(3) which displays a button in-
			    stead of a text input.
     AG_VBox(3)		    Alternate interface	to AG_Box(3).

     The ag_vg library is a simple 2D vector graphics library which allows de-
     velopers 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 ap-

     Following the same	design philosophy as the Agar-GUI, ag_vg only provides
     the entity	classes	(e.g., lines, arcs) useful to the widest range of ap-
     plications, and allows specialized	and application-specific entities to
     be	implemented easily in separate libraries.  For specialized applica-
     tions such	as CAD systems,	the placement of entities might	be best	de-
     scribed through geometrical constraints (e.g., distances and angles) as
     opposed to	linear transformations.	 This functionality is implemented,
     notably, by the FreeSG library:

     To	use this library, link against `agar-vg-config --libs'.

     VG(3)	     Vector drawing object.
     VG_View(3)	     Agar widget for visualization and edition of drawings.
     VG_Arc(3)	     Arc entity.
     VG_Circle(3)    Circle entity.
     VG_Line(3)	     Line entity.
     VG_Polygon(3)   Polygon entity.
     VG_Text(3)	     Text entity.

     ag_math is	a general-purpose math library focused on providing consistent
     structures	and highly optimized routines.	In addition to linear algebra,
     ag_math also provides useful computational	geometry structures and	meth-
     ods (e.g.,	intersections, tesselations), portable complex-number/quater-
     nion routines and some useful Agar-GUI widgets and	extensions.

     To	use this library, link against `agar-math-config --libs'.

     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 op-
		       timizations), as	well as	a specialized interface	for
		       4x4 matrices (usually countered in computer graphics).
     M_Circle(3)       Circles in R^2 and R^3.
     M_Color(3)	       Mapping between different color spaces.
     M_Complex(3)      Complex-number arithmetic not reliant on	compiler ex-
     M_Coordinates(3)  Mapping between different coordinate systems.
     M_Sort(3)	       Sorting algorithms (qsort, heapsort, mergesort, radix-
     M_IntVector(3)    Vector operations for vectors with integer elements.
     M_String(3)       Math-specific extensions	to the AG_Printf(3) formatting
     M_Line(3)	       Routines	related	to lines, half-lines and line seg-
     M_Matview(3)      Agar-GUI	widget for viewing the contents	of M_Matrix(3)
		       objects numerically or graphically.
     M_Plane(3)	       Routines	related	to planes in R^3.
     M_Plotter(3)      General-purpose plotting	widget for Agar-GUI, with sup-
		       port for	M_Real,	M_Vector and M_Complex types.
     M_PointSet(3)     Set of points and related operations (e.g., convex
     M_Polygon(3)      Operations related to polygons in R^2 and R^3.
     M_Quaternion(3)   Basic quaternion	arithmetic.
     M_Rectangle(3)    Routines	specific to rectangles in R^2 and R^3.
     M_Triangle(3)     Routines	specific to triangles in R^2 and R^3.
     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.

     The ag_au library provides	a basic	cross-platform interface to audio

     To	use this library, link against `agar-au-config --libs'.

     AU(3)	    Audio library initialization.
     AU_Wave(3)	    Structure containing an audio stream.
     AU_DevOut(3)   Interface to audio output device.

BSD			       NOVEMBER	26, 2001			   BSD


Want to link to this manual page? Use this URL:

home | help