.\" Copyright (c) 2011 Hypertriton, Inc. .\" 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 SEPTEMBER 1, 2010 .Dt SG_INTRO 3 .Os .ds vT FreeSG API Reference .ds oS FreeSG 1.0.0 .Sh NAME .Nm SG_Intro .Nd FreeSG introduction .Sh DESCRIPTION FreeSG is a general-purpose scene-graph library built on top of the Agar library (http://libagar.org/). FreeSG implements a compact and easily extensible object/scene graph representation, designed to simplify such tasks as real-time rendering and geometrical queries. .Pp In addition to the base scene-graph library (libfreesg), the FreeSG distribution also includes a separate library for geometrically constrained 2D sketching (libfreesg_sk), and a library for tiling (libfreesg_map). These libraries share the same version number and release cycle, but they are separate and can be always packaged and distributed independently. .Sh USING THE FREESG API REFERENCE Since the FreeSG API Reference is also intended as a detailed specification (defining function prototypes, structures and function behavior in detail), the content can become repetitive and difficult to read, so the API Reference uses a number of 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 the standard Agar function .Xr AG_GetError 3 . .It When FreeSG and Agar are both 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 which also apply to FreeSG). .El .Pp FreeSG uses the Agar object system. There is generally one manual page per Agar object class. 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 SG LIBRARY The base .Em freesg library implements scene rendering and geometrical methods in 3D. .Pp To use this library, link against .Sq freesg-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 (using boundary representation). .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 A texture compiled from a set of surfaces. May also be used to specify parameters for the fixed lighting model. .It Xr SG_Triangle 3 Triangle (reference geometry). .It Xr SG_View 3 Agar visualization widget for displaying a SG scene. .It Xr SG_Voxel 3 Voxel object. .El .Sh SK LIBRARY The .Em freesg_sk library implements the standard dimensioned 2D sketching capabilities one would find in a modern CAD application. Sketches can contain sets of metric relations (i.e., distances, angles) and logical relations (i.e., coincidence, parallelism, tangency), and the SK solver attempts to find a solution using degree-of-freedom analysis. .Pp To use this library, link against .Sq freesg-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 MAP LIBRARY The .Em freesg_map library implements scenes constructed from traditional 2D tiling methods. .Pp To use this library, link against .Sq freesg-map-config --libs . .Pp .Bl -tag -width "MAP_View (3) " -compact .It Xr MAP 3 Base map object. .It Xr MAP_Actor 3 Map object rendered dynamically. .It Xr MAP_View 3 Agar visualization widget for map objects. .El