diff options
| author | Michele Calgaro <[email protected]> | 2020-09-11 14:38:47 +0900 |
|---|---|---|
| committer | Michele Calgaro <[email protected]> | 2020-09-11 14:38:47 +0900 |
| commit | 884c8093d63402a1ad0b502244b791e3c6782be3 (patch) | |
| tree | a600d4ab0d431a2bdfe4c15b70df43c14fbd8dd0 /debian/fireflies/fireflies-2.08/libgfx/doc | |
| parent | 14e1aa2006796f147f3f4811fb908a6b01e79253 (diff) | |
| download | extra-dependencies-884c8093d63402a1ad0b502244b791e3c6782be3.tar.gz extra-dependencies-884c8093d63402a1ad0b502244b791e3c6782be3.zip | |
Added debian extra dependency packages.
Signed-off-by: Michele Calgaro <[email protected]>
Diffstat (limited to 'debian/fireflies/fireflies-2.08/libgfx/doc')
25 files changed, 2565 insertions, 0 deletions
diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/build.html b/debian/fireflies/fireflies-2.08/libgfx/doc/build.html new file mode 100644 index 00000000..e373c81e --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/build.html @@ -0,0 +1,135 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: build.html 334 2002-04-02 17:01:32Z garland $ --> + +<html> + +<head> +<title>libgfx: Building the Library</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Building the Library</h2> + +<p><tt>libgfx</tt> is a C++ library which is meant to be fairly easy +to compile on a wide range of systems. It was developed under Windows +NT 4.0, Windows 2000, and RedHat Linux 6. + +<p>This library does make use of the ANSI C++ Standard Library. For +instance, it uses the new <tt><iostream></tt> rather than the +old <tt><iostream.h></tt> package. And it does make some +minimal use of the Standard Template Library (STL). Therefore, it may +not work on older C++ compilers. It is known to work on Microsoft +Visual C++ version 5.0 and above and GNU GCC version 2.9 and above. + +<p><strong>Required</strong> external libraries: +<ul> +<li>The <a href="http://www.fltk.org">FLTK</a> graphical interface toolkit. +<li>An <a href="http://www.opengl.org">OpenGL</a> library +or the <a href="http://www.mesa3d.org">Mesa</a> library. +</ul> + + +<p><strong>Optional</strong> external libraries: +<ul> +<li>The <a href="http://www.libtiff.org">libtiff</a> library for TIFF image +file support + +<li>The JPEG support library from the +<a href="http://www.ijg.org">Independent JPEG Group</a> + +<li>The <a href="http://www.libpng.org/pub/png/">libpng</a> library +for PNG image file support. + +</ul> + + +<h3>For Windows Systems</h3> + + + + +<h4>Visual C++</h4> + +<p>A Visual C++ 6.0 workspace and accompanying project files are +provided in the <tt>vc6</tt> directory. +An older VC++ 5.0 workspace is available in the <tt>vc5</tt> directory. +However, this is no longer in regular use and may be out of date. + +<h5>Manual Build</h5> + +<p>The library can also be built manually using the <tt>nmake</tt> +command line tool. A <tt>configure.bat</tt> batch file is provided +which will set up the necessary configuration files. + +<p>To build the library manually, use the following process: +<ol> +<li><tt>configure.bat</tt> +<li><tt>cd src</tt> +<li><tt>nmake /f Makefile.vc</tt> +</ol> + + +<h4>Cygwin</h4> + +<p>The <tt>libgfx</tt> library will build properly under Windows with + the <a href="http://sourceware.cygnus.com/cygwin/">Cygwin</a> + toolset. Simply follow the directions for <a href="#unix">Unix + systems</a>. + + + + +<h3><a name="unix">For Unix Systems</a></h3> + +<p>The Unix build process relies on the GNU +<a href="http://www.gnu.org/software/autoconf/autoconf.html">Autoconf</a> +system to properly configure the software. + +<p>Once the required libraries are installed, you should be able to +build the library using the following process: +<ol> +<li><tt>./configure</tt> +<li><tt>cd src</tt> +<li><tt>make</tt> +</ol> +If the support libraries are installed in a directory outside the default +search path, you can invoke the <tt>configure</tt> script with the option +<tt>--with-local[=dir]</tt> which will add "dir" to the search path. The +default local directory is <tt>/usr/local</tt>, but you can specify any +directory of your choice. + +<h3><a name="macosx">For Mac OS X Systems</a></h3> + +<p>The current version of <tt>libgfx</tt> can be successfully compiled +under Mac OS X, but it requires a bit of manual intervention. + +<p>First, you should install the FLTK library. To build under Mac OS X, +you must use version 1.1.0 or later. +Next, you should follow the instructions for using the Autoconf +script outlined in the <a href="#unix">directions for Unix systems</a> +above. + +<p>This is sufficient to compile command-line programs. However, GUI +programs require a little extra work. The typical GUI <tt>make</tt> rule looks +like this: +<pre> + gui-program: gui-program.cxx + $(CXX) -o $@ $^ $(CXXFLAGS) $(LDFLAGS) -lgfx $(GUI_LIBS) -lm +</pre> +To work correctly with the Mac OS, you must add an additional step to +this <tt>make</tt> rule: +<pre> + gui-program: gui-program.cxx + $(CXX) -o $@ $^ $(CXXFLAGS) $(LDFLAGS) -lgfx $(GUI_LIBS) -lm + $(FLTKCONFIG) --post $@ +</pre> +This uses the <tt>fltk-config</tt> script to add a standard resource +fork to the compiled application. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/cdoc.css b/debian/fireflies/fireflies-2.08/libgfx/doc/cdoc.css new file mode 100644 index 00000000..289832b6 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/cdoc.css @@ -0,0 +1,86 @@ +/* + * Stylesheet for code documentation + * + * $Id: cdoc.css 268 2001-10-02 16:09:20Z garland $ + */ + +BODY { + font-family: "Times New Roman", "Times", serif; + background-color: white; + color: black; +} + +@media screen { + BODY { + margin-left: 11.11%; + margin-right: 11.11%; + } + + /* To be used for floating navbars */ + DIV.navbar { + font-family: Arial Narrow; + display: block; + text-align: left; + float: right; + padding-bottom: 2pt; + padding-left: 2pt; + border-left: thin dashed black; + border-bottom: thin dashed black; + } +} + +@media print { + /* IE often prints Web pages in excessively large fonts */ + BODY { font-size: 10pt; } + + /* Navbars should not be printed */ + DIV.navbar { display: none } + + /* H2 headers are used as the top-level elements for separate sections */ + H2 { page-break-before: always } +} + +H1, H2, H3, H4, H5, H6 { clear: both; font-family: Arial, sans-serif; } +H1 { font-size: 249% } +H2 { font-size: 172%; } +H3 { font-size: 144%; } +H4 { font-size: 120%; margin-bottom: 0.5em; } +H5,H6 { font-size: 100%; margin-bottom: 0.2em; } + +H1, H2, H3, H4 { + color: #4444aa; + background-color: #cccccc; + padding-top: 4px; + padding-left: 4px; + padding-right: 4px; + padding-bottom: 4px; +} + +H1,H2 { margin-left: -1.5em; } +H3 { margin-left: -0.75em; } + +P { text-indent: 0pt; } +P.indent { text-indent: 1em; } +P.justify { text-align: justify; } + +PRE.code { margin-left: 2em } + +/* The standard size scale */ +.min5 { font-size: 40%; } +.min4 { font-size: 48%; } +.min3 { font-size: 58%; } +.min2 { font-size: 69%; } +.min1 { font-size: 83%; } +.min0 { font-size: 100%; } +.mag0 { font-size: 100%; } +.mag1 { font-size: 120%; } +.mag2 { font-size: 144%; } +.mag3 { font-size: 172%; } +.mag4 { font-size: 207%; } +.mag5 { font-size: 249%; } + +/* Link styles */ +A { text-decoration: none } +A:active {color: red} +A:hover {color: red} +A:visited {color: purple} diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/ex-gui.html b/debian/fireflies/fireflies-2.08/libgfx/doc/ex-gui.html new file mode 100644 index 00000000..d1e0a1be --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/ex-gui.html @@ -0,0 +1,238 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: ex-gui.html 173 2000-09-07 02:57:34Z garland $ --> + +<!-- Based on ../tests/t-gui.cxx revision 1.3 --> + +<html> + +<head> +<title>libgfx: Simple GUI Example Program</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> + +<style type="text/css"> +<!-- +pre { margin-left: 2em } +--> +</style> + +</head> + +<body> + +<h2>Simple GUI Example Program</h2> + +<p>This is a very simple program which uses the minimalist <a +href="gui.html">GUI</a> facility provided by <tt>libgfx</tt> +to create a window a draw a red square in it. When first started, it +presents the user with a window which looks like the one shown below. +The full source code for this example application can be found in +the file <tt>tests/t-gui.cxx</tt> in the <tt>libgfx</tt> source +distribution. + +<p> +<div align=center> +<img src="gui-redbox.gif"> +</div> + +<h3>Setup</h3> + +<p>The program begins by including some of the standard +<tt>libgfx</tt> headers. + +<pre> +#include <gfx/gfx.h> +#include <gfx/gui.h> +#include <gfx/gltools.h> +</pre> + +<p>The first step in using the <tt>libgfx</tt> GUI framework is to +subclass the <tt>MxGUI</tt> class and override whatever handlers you +want to write code for. After defining the subclass, you must then +create a <em>single</em> instance. In this application, we override +the handlers involved with drawing and mouse events. +We also follow the recommended idiom of naming our derived subclass +<tt>GUI</tt> and its lone instance <tt>gui</tt>. + +<pre> +class GUI : public MxGUI +{ +public: + float angle, opt_theta, center[2]; + bool dragging; + +public: + <i>// Drawing-related handler methods</i> + virtual void setup_for_drawing(); + virtual void draw_contents(); + virtual void update_animation(); + + <i>// Mouse-related handler methods</i> + virtual bool mouse_down(int *where, int which); + virtual bool mouse_up(int *where, int which); + virtual bool mouse_drag(int *where, int *last, int which); +}; + +GUI gui; +</pre> + + +<h3>Application Entry Point</h3> + +<p><tt>MxGUI</tt> programs always use the <tt>main()</tt> procedure as +their entry point, even on Windows systems. This application follows +the recommended sequence of actions +<ol> +<li>Initialize member variables defined by the <tt>GUI</tt> derived class. +<li>Call <tt>gui.initialize()</tt> to parse the command line and +create the application. +<li>Customize the default application by changing labels, adding +menus, etc. +<li>And finally, call <tt>gui.run()</tt> to open the application +window and begin the event loop. +</ol> +These four distinct phases are indicated in the program source by +whitespace-separated blocks. + +<pre> +main(int argc, char **argv) +{ + gui.opt_theta = 10.0f; + gui.angle = 0.0f; + gui.dragging = false; + gui.center[0] = gui.center[1] = 0.0f; + + gui.initialize(argc, argv); + + gui.toplevel->label("Simple GUI Example"); + + return gui.run(); +} +</pre> + +<h3>Drawing-Related Handler Methods</h3> + +<p>Whenever our OpenGL drawing canvas is created, resized, or +otherwise reconfigured, the <tt>setup_for_drawing()</tt> handler is +invoked. This is where you want to set up any graphics state that is +the same for every frame. + +<pre> +void GUI::setup_for_drawing() +{ + glClearColor(0.65f, 0.65f, 0.65f, 0.0f); + glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); + + glMatrixMode(GL_PROJECTION); + gluOrtho2D(-1.0, 1.0, -1.0, 1.0); +} +</pre> + + +<p>If the contents of the OpenGL canvas need to be redrawn, the +<tt>draw_contents()</tt> handler is invoked. + +<pre> +void GUI::draw_contents() +{ + glClear(GL_COLOR_BUFFER_BIT); + + glMatrixMode(GL_MODELVIEW); + glPushMatrix(); + glLoadIdentity(); + + <i>// Draw the black axes</i> + glColor3f(0.0, 0.0, 0.0); + glBegin(GL_LINES); + glVertex2f(-1.0, 0.0); + glVertex2f(1.0, 0.0); + glVertex2f(0.0, -1.0); + glVertex2f(0.0, 1.0); + glEnd(); + + glTranslatef(center[0], center[1], 0); + glRotatef(angle, 0, 0, 1); + + <i>// Draw the red rectangle</i> + glEnable(GL_BLEND); + glColor4d(0.8, 0.15, 0.15, 0.85); + glBegin(dragging?GL_LINE_LOOP:GL_POLYGON); + glBegin(GL_POLYGON); + glVertex2f(-0.5, -0.5); + glVertex2f(-0.5, 0.5); + glVertex2f(0.5, 0.5); + glVertex2f(0.5, -0.5); + glEnd(); + glDisable(GL_BLEND); + + glPopMatrix(); +} +</pre> + +<p>The <tt>MxGUI</tt> framework provides a simplistic animation +mechanism. Whenever animation is activated --- the user controls this +via a menu entry --- the event loop will periodically call the +<tt>update_animation()</tt> handler. +<pre> +void GUI::update_animation() +{ + angle += opt_theta; +} +</pre> + +<h3>Mouse-Related Handler Methods</h3> + +<p>When the user clicks the left mouse button, we want to re-center +the square around that position. We use a call to the +<tt>unproject_pixel()</tt> <a href="gl.html">utility function</a> +to map the pixel location into a world-space coordinate. + +<pre> +static bool center_on_click(float *ctr, int *where) +{ + double world[3]; + + unproject_pixel(where, world); + ctr[0] = (float)world[0]; + ctr[1] = (float)world[1]; + + return true; +} +</pre> + +<p>Given the above code to center the rectangle on a click location, +it is a simple matter to write our mouse handlers. Whenever the +left button is pressed or dragged, we recenter the rectangle. We also +maintain the value of <tt>gui.dragging</tt> to indicate whether the +mouse is being dragged. If it is, the <tt>draw_contents()</tt> +handler will draw the rectangle as an outline rather than a filled box. + +<pre> +bool GUI::mouse_down(int *where, int which) +{ + if( which==1 ) + { + dragging = true; + return center_on_click(center, where); + } + else return false; +} + +bool GUI::mouse_up(int *where, int which) +{ + dragging = false; + return (which==1); +} + +bool GUI::mouse_drag(int *where, int *last, int which) +{ + if( which==1 ) + return center_on_click(center, where); + else + return false; +} +</pre> + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/ex-script.html b/debian/fireflies/fireflies-2.08/libgfx/doc/ex-script.html new file mode 100644 index 00000000..56124fb4 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/ex-script.html @@ -0,0 +1,153 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: ex-script.html 269 2001-10-10 00:38:28Z garland $ --> + +<!-- Based on ../tests/t-script.cxx revision 1.6 --> + +<html> + +<head> +<title>libgfx: Simple Scripted Program</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> + +<style type="text/css"> +<!-- +pre { margin-left: 2em } +--> +</style> + +</head> + +<body> + +<h2>Simple Scripted Program</h2> + +<p>This program demonstrates some of the basic features provided by the +<tt>libgfx</tt> <a href="script.html">scripting package</a>. Given a list of +file names on the command line, it reads each of them in turn and executes the +scripting commands contained within them. + +<h3>Setup and Initialization</h3> + +<p>The program begins by including the headers for the <tt>libgfx</tt> modules +which it uses: +<pre> +#include <gfx/gfx.h> +#include <gfx/script.h> +#include <gfx/vec3.h> +</pre> + +<p>The <tt>main()</tt> application entry point performs a very simple task. +It creates a scripting environment (<tt>class CmdEnv</tt> and registers a set +of scripting commands. Once these handlers have been installed, +it loops over every file name specified on the command line and executes it as +a script. +<pre> +main(int argc, char *argv[]) +{ + CmdEnv env; + + env.register_command("add", proc_add); + env.register_command("avg", proc_add); + env.register_command("echo", proc_echo); + env.register_command("vec3", proc_vec3); + + for(int i=1; i&argc; i++) + script_do_file(argv[i], env); + + return 0; +} +</pre> + +<h3>Command Procedures</h3> + +<p>Every scripting command is handled by some command procedure. The +registration code above binds the actual procedures to the names of their +scripting commands. Then, whenever a given command occurs in a script being +processed, the corresponding handler is invoked. + +<p>The first command procedure actually implements two scripting commands: +<tt>add</tt> and <tt>avg</tt>. It determines which command has been invoked +by examining its <tt>name</tt> argument. +It treats its command line as a whitespace-separated sequence of numbers, +either adds or averages all of them, and then prints the result. +<pre> +int proc_add(const CmdLine &cmd) +{ + double sum = 0.0; + int count; + + std::vector<double> values; + cmd.collect_as_numbers(values); + for(count=0; count<values.size(); count++) + sum += values[count]; + + if( cmd.opname() == "avg" && count>0 ) + sum /= (double)count; + + cout << sum << endl; + return SCRIPT_OK; +} +</pre> + +<p>This next procedure requires precisely 3 numeric arguments, from which it +constructs a 3-D vector using the <tt>Vec3</tt> class. If the number of +arguments is not 3, it returns a value indicating a syntax error occurred. +<pre> +int proc_vec3(const CmdLine &cmd) +{ + if( cmd.argcount() != 3 ) return SCRIPT_ERR_SYNTAX; + + Vec3 v; + cmd.collect_as_numbers(v, 3); + + cout << v << endl; + return SCRIPT_OK; +} +</pre> + +<p>Finally, the <tt>echo</tt> procedure does not interpret its arguments at +all. Instead, it simply prints the entire argument line as is. +<pre> +int proc_echo(const CmdLine &cmd) +{ + cout << cmd.argline() << endl; + return SCRIPT_OK; +} +</pre> + +<h3>Sample Execution</h3> + +<p>To demonstrate the action of this sample program, here is a particularly +simple script. +<pre> +# This is a test script meant to be fed to t-script. It is not meant as an +# exhaustive test, but mainly as a demonstration. + +echo The following sum should be 15 +add 1 2 3 4 5 + +echo +echo The following average should be 3.5 +avg 3 8 2 1 + +echo +echo The following is the vector [1 0 0] +vec3 1 0 0 +</pre> + +<p>When given to the sample program, it produces the following output +<pre> +The following sum should be 15 +15 + +The following average should be 3.5 +3.5 + +The following is the vector [1 0 0] +1 0 0 +</pre> + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/geom3d.html b/debian/fireflies/fireflies-2.08/libgfx/doc/geom3d.html new file mode 100644 index 00000000..549aa7a7 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/geom3d.html @@ -0,0 +1,59 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: geom3d.html 160 2000-09-05 19:44:15Z garland $ --> + +<html> + +<head> +<title>libgfx: 3-D Geometric Procedures</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>3-D Geometric Procedures</h2> + +<p>Triangles are a very common modeling primitive in many graphics +applications. The <tt>libgfx</tt> library provides a package of routines for +computing various geometric properties of triangles. +To use this package you must include the standard header file +<pre> + #include <gfx/geom3d.h> +</pre> +Note that all of these functions assume that the corners of the triangle are +listed in <em>counter-clockwise order</em> around the outward pointing normal. + +<p>You can compute the (signed) area of a triangle using the following +function. Note that the area will be negative if the vertices are listed in +clockwise order. +<pre> + double triangle_area(const Vec3&, const Vec3&, const Vec3&); +</pre> + +<p>The following functions compute the plane defined by a triangle, and the +corresponding normal vector. The standard versions always use unit normal +vectors while the "raw" versions will use unscaled normals. +<pre> + Vec3 triangle_normal(const Vec3&, const Vec3&, const Vec3&); + Vec4 triangle_plane(const Vec3&, const Vec3&, const Vec3&); + + Vec3 triangle_raw_normal(const Vec3&, const Vec3&, const Vec3&); + Vec4 triangle_raw_plane(const Vec3&, const Vec3&, const Vec3&); +</pre> + + +<p>For some meshing applications, it may on occasion be necessary to assess +the aspect ratio of a triangle. +<pre> + double triangle_compactness(const Vec3&, const Vec3&, const Vec3&); +</pre> +This function computes the "compactness" of a triangle. The returned value +will be between 0 and 1, with 0 meaning a degenerate (area=0) triangle and 1 +meaning an equilateral triangle. The formula used, originally suggested by +Andre Gueziec, is 4*sqrt(3) * Area / (L1 + L2 + L3) where Li is the squared +length of side <i>i</i> of the triangle. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/gl.html b/debian/fireflies/fireflies-2.08/libgfx/doc/gl.html new file mode 100644 index 00000000..a00ba9ab --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/gl.html @@ -0,0 +1,112 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: gl.html 156 2000-09-05 16:33:04Z garland $ --> + +<html> + +<head> +<title>libgfx: OpenGL Support</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>OpenGL Support</h2> + +<p> + + +<p><strong>Important:</strong> +The standard way to include the OpenGL headers is to include the +headers + +<pre> + #include <GL/gl.h> + #include <GL/glu.h> +</pre> + +However, to ensure portability you <em>should not</em> do this; use +the following inclusion instead: + +<pre> + #include <gfx/gl.h> +</pre> + +The primary reason for this is that the Microsoft OpenGL headers do +not work properly unless you have included <tt><windows.h></tt> +first. This <tt>libgfx</tt> header takes care of the necessary +<tt>#ifdefs</tt> and keeps your code looking cleaner. + + +<h3>Utility Functions</h3> + + +To gain access to these utility functions, include the header + +<pre> + #include <gfx/gltools.h> +</pre> + +<p>Given a pixel coordinate in the OpenGL viewport, it is often +necessary to project this to a 3-D point in the world being displayed. +You can use the function +<pre> + int unproject_pixel(int *pixel, double *world, double z=0.0); +</pre> +to accomplish this. + + + +<p>To simplify the display of 3-D scenes, the function +<pre> + void camera_lookat(const Vec3& min, const Vec3& max, double aspect); +</pre> +will set up a standard viewing geometry for displaying an object +bounded by the axis-aligned box [<tt>min</tt>, <tt>max</tt>] in a +window whose aspect ratio is <tt>aspect</tt>. +The camera will be looking at the center of the box, from a position +further along the <i>z</i> axis, with a 60° field of view. +The viewing transform will be multiplied into the current matrix, +using calls to <tt>gluPerspective()</tt> and <tt>gluLookAt()</tt>. + +<p>Errors during OpenGL processing are not reported to the user, they are +merely flagged in the current OpenGL state. To check for and report any +OpenGL errors, you can call the function: +<pre> + void check_opengl_errors(const char *msg=NULL); +</pre> +An optional message can be provided which will be prepended to the error +reported (if any). + +<h4>Picking</h4> + +<p>Interactive programs frequently need to allow the user to select +individual components of the scene being displayed by clicking on the +rendered image. Given a pixel location in the window, the application +must determine which entity the user clicked on. +The standard technique for doing this with OpenGL is with the selection +buffer. The <tt>libgfx</tt> library provides some utility functions to make +using the selection buffer somewhat easier. +Details on using the selection buffer can be found in the OpenGL Programming +Guide. + +<p>Before drawing your primitives, call the function +<pre> + void begin_opengl_pick(int *ctr, double radius, GLuint *buf, int size); +</pre> +with the location of the user's pointer (<tt>ctr</tt>) and +the <tt>radius</tt> of the region to consider. You will also need to allocate +and pass a buffer of object identifiers to hold the candidate objects. +Having set things up, you can draw your primitives as usual, assigning an +integer identifier to each using the <tt>glLoadName()</tt> function. +After all primitives have been drawn, call the function +<pre> + GLuint complete_opengl_pick(GLuint *buffer); +</pre> +The returned value will be the identifier of the object clicked on, or +<tt>opengl_pick_nil</tt> if the user clicked on the background. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/gui-layout.gif b/debian/fireflies/fireflies-2.08/libgfx/doc/gui-layout.gif Binary files differnew file mode 100644 index 00000000..767daa05 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/gui-layout.gif diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/gui-redbox.gif b/debian/fireflies/fireflies-2.08/libgfx/doc/gui-redbox.gif Binary files differnew file mode 100644 index 00000000..d53d89fd --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/gui-redbox.gif diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/gui.html b/debian/fireflies/fireflies-2.08/libgfx/doc/gui.html new file mode 100644 index 00000000..01031805 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/gui.html @@ -0,0 +1,257 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: gui.html 307 2002-03-11 21:15:37Z garland $ --> + +<html> + +<head> +<title>libgfx: Minimalist GUI Framework</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Minimalist GUI Framework</h2> + +<p>All interactive graphics applications need to create some sort of graphical +user interface. While many applications may require a fairly sophisticated +interface, there is a large class of applications which can be built with a +very simple interface. The <tt>libgfx</tt> library provides a framework to +ease the construction of such simple interfaces. + +<p>The kind of application interface supported by the GUI framework is +pictured in the following figure: +<blockquote> +<center><img src="gui-layout.gif"></center> +</blockquote> + +The application window consists of three primary components: +<ol> +<li>A menu bar, which is managed by the GUI framework, +<li>An OpenGL canvas window where the application is free to draw its content +and receive user events such as mouse clicks, and +<li>A status bar where the application can print text messages. +</ol> + +<p>The <a href="ex-gui.html">code for the application pictured +above</a> provides a concrete example of using this GUI framework. + +<h3>Creating a GUI Application</h3> + +<p>To begin building your GUI application, you'll need to include the GUI +framework header: +<pre> + #include <gfx/gui.h> +</pre> +The framework itself is packaged as a C++ class named <tt>MxGUI</tt>. +You create your application by subclassing it and overriding various virtual +methods. You can then create a single instance of this class, which will +represent your application. +For consistency, it is recommended that you name +the derived subclass <tt>GUI</tt> and its instance <tt>gui</tt> as in the +following: +<pre> + class GUI : public MxGUI + { + public: + <i>// Application variables and methods</i> + + public: + <i>// Override virtual methods to handle events</i> + }; + + GUI gui; <i>// Create application instance</i> +</pre> + +<p>Programs based using this framework always use the <tt>main()</tt> +procedure as their entry point, <em>even on Windows systems</em>. +Inside this main procedure, you should perform this general sequence of +operations: +<ol> +<li>Initialize global variables and member variables defined in the +<tt>GUI</tt> class. +<li>Call the <tt>gui.initialize()</tt> procedure to parse the command line and +create the application. +<li>Customize the default application by changing labels, adding menus, etc. +<li>Call <tt>gui.run()</tt> to open the application window and begin the event +loop. +</ol> + +<p>The <tt>MxGUI::initialize</tt> method must be called to initialize the GUI +framework. +<pre> + virtual void initialize(int argc, char **argv, + Fl_Menu_Item *layout=NULL, int xw=640, int yw=480); +</pre> +You should pass to it the <tt>argc</tt> and <tt>argv</tt> command-line +variables as passed into <tt>main()</tt>. The framework will take care of +parsing the command-line and calling the appropriate handlers. +The optional <tt>layout</tt> argument can be used to specify an initial menu +structure; the default value of <tt>NULL</tt> directs the framework to use the +default menu layout. +The optional <tt>xw</tt> and <tt>yw</tt> arguments specify the desired width +and height (in pixels) of the OpenGL canvas. + +<h4>Command-Line Processing</h4> + +<p> +The <tt>MxGUI</tt> framework uses the FLTK +<a href="http://www.fltk.org/doc-1.0/functions.html#args"><tt>Fl::args</tt></a> +facility to parse the command line passed to <tt>MxGUI::initialize()</tt>. +For each option on the command line, it invokes the following handler: +<pre> + virtual int cmdline_option(int argc, char **argv, int& index); +</pre> +The <tt>argc</tt> and <tt>argv</tt> values are the complete array originally +passed to <tt>initialize()</tt>. The <tt>index</tt> argument indicates which +element of <tt>argv</tt> contains the current switch being processed. +This <tt>index</tt> variable is passed by reference to allow the handler to +consume additional elements of <tt>argv</tt> by incrementing <tt>index</tt>. +The handler should return <tt>1</tt> if it handled the switch and <tt>0</tt> +otherwise. + +<p>Once all options have been processed, the initialization code invokes the +following handler for each file listed on the command line. +<pre> + virtual void cmdline_file(const char *file); +</pre> +If no files are specified this handler will be invoked with a <tt>NULL</tt> +value. + +<h4>Drawing</h4> + +<p>The <tt>MxGUI</tt> framework uses two virtual methods to control drawing in +the OpenGL canvas. The first of these is: +<pre> + virtual void setup_for_drawing(); +</pre> +This method is called whenever the canvas has been reconfigured. Primarily, +this occurs when the canvas has either just been shown on the screen (e.g., +after creation) or when it has been resized. + +<p>Whenever the canvas needs to be repainted, the framework will invoke the +handler: +<pre> + virtual void draw_contents(); +</pre> +You should override this method and place all your drawing code in it. + + +<h4>Handling Mouse Events</h4> + +<p>Interactive applications will typically want to receive mouse events taking +place on the OpenGL canvas. The framework classifies mouse events into three +types: +<ol> +<li><strong>Button down:</strong> + the user has depressed a mouse button +<li><strong>Button up:</strong> + the user has released a previously depressed button +<li><strong>Drag:</strong> + the user is moving the mouse with a button depressed +</ol> +When one of these events occur, the corresponding event handler will be +invoked: +<pre> + virtual bool mouse_down(int *where, int which); + virtual bool mouse_up(int *where, int which); + virtual bool mouse_drag(int *where, int *last, int which); +</pre> +The <tt>where</tt> argument is a 2-D array containing the pixel location in +the OpenGL canvas at which the mouse was pointing when the event occurred. +The number of the button involved (either 1, 2, or 3) is passed in the +<tt>which</tt> argument. +To simplify drag operations, that event handler is also passed the location of +the <tt>last</tt> received drag event. + +<p>All of these mouse handlers should return <tt>true</tt> if the canvas +should be redrawn in response to the event just handled. If the canvas does +not need to be updated, they should return <tt>false</tt>. + +<h4>Handling Key Presses</h4> + +<p>Key press events can be received through the virtual function: +<pre> + virtual bool key_press(int key); +</pre> +The return value of this function indicates whether the key press event +was consumed by the handler. You should make sure to return +<tt>false</tt> if you do not use the given key, otherwise keyboard +accelerators for the menu bar will no longer function correctly. + +<p>Note that FLTK defines +<a + href="http://www.fltk.org/doc-1.0/enumerations.html#key_values">symbolic + names</a> for non-ASCII keys. You can also query the state of the +modifier keys using the <tt><a href="http://www.fltk.org/doc-1.0/enumerations.html#13_6">Fl::event_state()</a></tt> function. + +<h4>Animation</h4> + +<p>A very simple mechanism for supporting animation is also provided by the +framework. To take advantage of this, first set the <tt>MxGUI</tt> instance +variable +<pre> + float default_fps; +</pre> +to the desired number of frames per second (defaults to 24). The method +<pre> + void animate(bool will); +</pre> +can then be used to start and stop animation. +The system works by setting a system timer to go off every 1/fps of a second. +When that timer goes off, the framework will call the handler +<pre> + virtual void update_animation(); +</pre> +so that the application can update its state appropriately, after which the +framework will invoke the <tt>draw_contents()</tt> handler to repaint the +canvas. Note that this system makes no effort to guarantee a consistent +update rate. + +<p>The default menu bar contains items to toggle animation on and off and to +set the desired <tt>default_fps</tt> value. + + +<h3>The Menu Bar</h3> + +<p>Many GUI applications use menu systems to provide the user control over the +application. By default, the <tt>MxGUI</tt> framework creates a very simple +menu layout for its applications. This standard menu provides basic features +such as saving a snapshot of the OpenGL canvas to an image file, toggling +animation, and setting the size of the display canvas. +However, the application also has complete freedom to customize the menu +system. + +<h4>Static Menu Layouts</h4> + +<p>The <tt>initialize()</tt> method accepts an optional argument which +specifies the layout of the menu system. This layout is an array of <a +href="http://www.fltk.org/doc-1.0/Fl_Menu_Item.html">Fl_Menu_Item</a> elements, +whose format is described in the <a +href="http://www.fltk.org/doc-1.0/Fl_Menu_Item.html">FLTK documentation</a>. +Passing a menu layout to <tt>initialize()</tt> will completely replace the +default menu structure. + +<h4>Adding Menus at Run Time</h4> + +<p>Once an initial menu system has been created, either the default or an +application-specific one, additional items can be added at run time. To do +this, you can invoke the <a +href="http://www.fltk.org/doc-1.0/Fl_Menu_.html#Fl_Menu_.add"><tt>add()</tt></a> +method of the <tt>MxGUI::menu_bar</tt> object. + + +<h3>The Status Bar</h3> + +<p>The status bar at the bottom of the GUI application can be used to display +short textual messages to the user. +You can use the following method to print text in the status bar: +<pre> + int status(const char *fmt, ...); +</pre> +It accepts argument lists of exactly the same form as the <tt>printf</tt> +function of the C standard library. + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/index.html b/debian/fireflies/fireflies-2.08/libgfx/doc/index.html new file mode 100644 index 00000000..5844b4ed --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/index.html @@ -0,0 +1,81 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: index.html 372 2003-06-26 10:46:43Z garland $ --> + +<html> + +<head> +<title>libgfx: A Library for Writing Graphics Programs</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h1>libgfx: A Graphics Library</h1> + +<p>This software and associated documentation files are +Copyright © 1999–2001 Michael Garland. +Please see the accompanying <a href="license.html">License</a> +for details. + + +<h2>Contents</h2> + +<ul> + <li><a href="#intro">Introduction</a> + <li><a href="build.html">Building the Library</a> + <li><a href="start.html">Getting Started</a> + + <li><a href="vec.html">Vector Math</a> + <ul> + <li><a href="vec2.html">2-D vectors</a> + <li><a href="vec3.html">3-D vectors</a> + <li><a href="vec4.html">4-D vectors</a> + </ul> + + <li><a href="mat.html">Matrix Math</a> + <ul> + <li><a href="mat2.html">2-D matrices</a> + <li><a href="mat3.html">3-D matrices</a> + <li><a href="mat4.html">4-D matrices</a> + </ul> + + <li><a href="intvec.html">Packed Integer Vectors</a> + <li><a href="quat.html">Quaternions</a> + <li><a href="geom3d.html">3-D Geometric Procedures</a> + <li><a href="gl.html">OpenGL Support</a> + <li><a href="raster.html">Raster Images</a> + <li><a href="gui.html">Minimalist GUI framework</a> + <li><a href="rotate.html">Interactive Rotation Control</a> + <li><a href="script.html">Simple File Format Scripting</a> + + <li>Example Programs + <ul> + <li><a href="ex-gui.html">Simple GUI Program</a> + <li><a href="ex-script.html">Simple Scripted Program</a> + </ul> + + <li><a href="license.html">Copyright Notice and License</a> +</ul> + + +<h2><a name="intro">Introduction</a></h2> + +<p>The purpose of this library is to simplify the creation of computer +graphics software. Specifically, it is targeted towards +cross-platform development using the +<a href="http://www.opengl.org">OpenGL</a> rendering API and the +<a href="http://www.fltk.org">FLTK</a> interface toolkit. +It is derived from the <a +href="http://www.uiuc.edu/~garland/software/qslim20.html">MixKit</a> library I +developed for supporting polygonal +<a href="http://www.uiuc.edu/~garland/research.html">surface +simplification</a>. +This is <em>not</em> a full-fledged graphics engine. Rather it +provides facilities which are useful in the majority of graphics +programs. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/intvec.html b/debian/fireflies/fireflies-2.08/libgfx/doc/intvec.html new file mode 100644 index 00000000..9c13957d --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/intvec.html @@ -0,0 +1,95 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: intvec.html 161 2000-09-05 20:29:15Z garland $ --> + +<html> + +<head> +<title>libgfx: Packed Integer Vectors</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Packed Integer Vectors</h2> + +<p>The <a href="vec.html">vector package</a> provides the standard way to +represent and manipulate vector quantities. +These vectors are primarily designed to represent real-valued vectors using +floating point numbers. +However, there are times when it is more convenient to use a packed integer +vector format. That is the purpose of this package, which you can use by +including the header file +<pre> + #include <intvec.h> +</pre> + +<p>A <em>packed integer vector</em> is an <i>n</i> element vector, each of whose +elements are <i>k</i>-bit integers. These <i>k</i>-bit integers are +interpreted as representing the range [0, 1] for unsigned types and [-1, 1] +for signed types. For example, suppose we have a vector whose elements are +unsigned 8-bit quantities (e.g., of type <tt>unsigned char</tt>). +Each value would have an integral value in the range [0, 255], but these +values would always be interpreted as real values ranging between [0, 1]. + +<h3>class IntVec</h3> +<p>Packed integer vectors are declared using the following template class +<pre> + template<class T, int T_MAX, int N> class IntVec; +</pre> +The type <tt>T</tt> is the type of the constituent elements (e.g., +<tt>unsigned char</tt>) and <tt>T_MAX</tt> is the maxium representable value +for this type (e.g., <tt>UCHAR_MAX</tt>). The number of elements in the +vector is determined by <tt>N</tt>. Note that ANSI C defines appropriate +maximum values of integer types in <limits.h>. + +<p>Classes created from the <tt>IntVec</tt> template provide a small set of +fundamental public methods: +<ul> +<li>A default constructor that initializes all elements of the vector to 0. + +<li>A C-style [] bracket accessor which returns, as a +<tt>double</tt> the appropriate element of the vector. + +<li>A vector assignment operator (<tt>v = w</tt>). + +<li>A scalar assignment operator (<tt>v = 3.14</tt>). +</ul> + +<h3>class IntVec3</h3> + +<p>Because 3-D vectors are particularly common in graphics applications, this +package provides explicit support for them. +<pre> + template <class T, int T_MAX> class IntVec3; +</pre> + +<p>In addition to the standard <tt>IntVec</tt> methods, <tt>IntVec3</tt> +provides the following additional constructors, all of which allow the values +of the vector to be explicitly initialized. +<pre> + IntVec3(double x, double y, double z); + IntVec3(const Vec3& v); + IntVec3(const float v[3]); + IntVec3(const double v[3]); +</pre> + +<p>It also provides the following methods for manipulating the elements of the +vector: +<pre> + Vec3 unpack() const; <i>// Return vector as Vec3</i> + void pack(const Vec3& v); <i>// Set vector from v</i> + void pack(double x, double y, double z); <i>// Set vector from x,y,z</i> +</pre> + +<p>A typical use of this class would be in defining a type for RGB colors +represented with 8 bits per channel. Such a type could be declared as +follows: +<pre> + typedef IntVec3<unsigned char, UCHAR_MAX> byteColor; +</pre> + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/license.html b/debian/fireflies/fireflies-2.08/libgfx/doc/license.html new file mode 100644 index 00000000..2e96b7d8 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/license.html @@ -0,0 +1,54 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: license.html 257 2001-07-26 19:20:44Z garland $ --> + +<html> + +<head> +<title>libgfx: License</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>License</h2> + + +<p><strong>Copyright Notice</strong> +<blockquote> +Copyright © 1999–2001 Michael Garland. All rights reserved. +</blockquote> + +<p><strong>Terms and Conditions</strong> + +<p>Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, and/or sell copies of the Software, and to permit persons +to whom the Software is furnished to do so, provided that the above +copyright notice(s) and this permission notice appear in all copies of +the Software and that both the above copyright notice(s) and this +permission notice appear in supporting documentation. + +<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL +INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING +FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +<p>Except as contained in this notice, the name of a copyright holder +shall not be used in advertising or otherwise to promote the sale, use +or other dealings in this Software without prior written authorization +of the copyright holder. + + + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/mat.html b/debian/fireflies/fireflies-2.08/libgfx/doc/mat.html new file mode 100644 index 00000000..4f43c019 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/mat.html @@ -0,0 +1,119 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: mat.html 159 2000-09-05 19:43:19Z garland $ --> + +<html> + +<head> +<title>libgfx: Matrix Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Matrix Math</h2> + +<p>The <tt>libgfx</tt> matrix math package is the companion to the +<a href="vec.html">vector package</a> and are intended to provide a convenient +way of writing vector/matrix equations. +Currently, only square matrices +of dimension 2x2 [<a href="mat2.html"><tt>Mat2</tt></a>], +3x3 [<a href="mat3.html"><tt>Mat3</tt></a>], +and 4x4 [<a href="mat4.html"><tt>Mat4</tt></a>]. + +<p>A matrix consists of <i>n*n</i> double precision floating point values. +Unlike the vector package, the matrix package is not yet template-based. +Matrix elements are accessed using 0-indexed (row, column) pairs. Thus, a 2x2 +identity matrix can be constructed as follows: +<pre> + Mat2 A; + + A(0, 0) = 1.0; + A(0, 1) = 0.0; + A(1, 0) = 0.0; + A(1, 1) = 1.0; +</pre> +The default constructors (as used above) initialize all elements to 0. All +matrix classes also provide constructors which accept a list of row vectors to +initialize their elements. Thus, the following example is equivalent to the +code above: +<pre> + Mat2 A(Vec2(1.0, 0.0), Vec2(1.0, 0.0)); +</pre> +Matrices can also be automatically case to <tt>double</tt> pointers. Since +matrices are stored in row-major order, the follow code would change element +(0, 1) of the matrix above: +<pre> + double *B = A; + B[1] = -1.0; +</pre> + +<p><strong>Warning:</strong> +For efficiency reasons, <em>accessors are not range checked</em>. +Thus you can legally write +<pre> + Mat2 v; + v(-10, 37) = 1.0; +</pre> +and generate an invalid memory access. + +<h3>Arithmetic Operators</h3> + +<p>Like the vector package, one of the primary goals of the matrix package is +to simplify the writing of vector/matrix equations. +To accomplish this, it makes use of C++ operator overloading. + +<p><strong>Assignment</strong> +Matrices can be assigned the values of other matrices or scalars. +A matrix assignment <tt>A = B</tt> copies the elements of <tt>B</tt> +into the corresponding elements of <tt>A</tt>. A scalar assignment +<tt>A = 1.0</tt> copies the given scalar, in this case <tt>1.0</tt>, +into each of the elements of <tt>A</tt>. + +<p><strong>Addition/Subtraction</strong> +Matrices can be added together either with the binary addition operator (<tt>C += A + B</tt>) or the additive assignment operator (<tt>A += B</tt>). +Subtraction operates similarly, using subtraction rather than addition +operators. + +<p><strong>Scalar Multiplication/Division</strong> +Matrices can be multiplied by scalar values using either the binary +operator (<tt>A * 2.0</tt>) or the accumulation operator (<tt>A *= +2.0</tt>). Scalar division operates similarly. + +<p><strong>Matrix/Vector Multiplication</strong> +Matrices can be multiplied together with a binary operator (<tt>A * +B</tt>). Matrices can also multiply vectors (<tt>A * v</tt>) which returns a +new vector. + +<h3>Standard Matrix Functions</h3> + +<p>All matrix classes support a standard set of functions for performing +common operations on matrices. The functions are: +<pre> +<i>// Constructs the outer product of the two vectors</i> +Mat_ outer_product(const Vec_ &u, const Vec_ &v); + +<i>// Returns the determinant of the matrix</i> +double det(const Mat_ &A); + +<i>// Returns the trace of the matrix (the sum of the diagonals)</i> +double trace(const Mat_ &A); + +<i>// Returns the transpose of A</i> +Mat_ transpose(const Mat_ &A); + +<i>// Returns the adjoint of A</i> +Mat_ adjoint(const Mat_ &A); + +<i>// Places the inverse of A in A_inv and returns det(A) +// The contents of A_inv are undefined if the inverse doesn't exist.</i> +double invert(Mat_ &A_inv, const Mat_ &A); +</pre> + +<p>Matrices can also be read from and written to C++ iostreams using the +standard <tt><<</tt> and <tt>>></tt> operators. + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/mat2.html b/debian/fireflies/fireflies-2.08/libgfx/doc/mat2.html new file mode 100644 index 00000000..a41a0cb7 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/mat2.html @@ -0,0 +1,46 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: mat2.html 159 2000-09-05 19:43:19Z garland $ --> + +<html> + +<head> +<title>libgfx: Matrix Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Matrix Math</h2> + +<h3>class Mat2</h3> + +<p>This class implements a 2x2 real-valued matrix. +Individual elements are represented with <code>double</code> precision +floating point numbers. To use the <tt>Mat2</tt> class you must include the +header +<pre> + #include <gfx/mat2.h> +</pre> + +<h4>Constructor Methods</h4> + +<p>The <tt>Mat2</tt> class defines the following set of constructors: + +<pre> + <i>// Initialize all elements to 0</i> + Mat2(); + + <i>// Initialize row 0 to [a b] and row 1 to [c d]</i> + Mat2(double a, double b, double c, double d); + + <i>// Initialize rows with given vectors</i> + Mat2(const Vec2 &r0,const Vec2 &r1); + + <i>// Copy values from A</i> + Mat2(const Mat2 &A); +</pre> + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/mat3.html b/debian/fireflies/fireflies-2.08/libgfx/doc/mat3.html new file mode 100644 index 00000000..d2c7a778 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/mat3.html @@ -0,0 +1,44 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: mat3.html 159 2000-09-05 19:43:19Z garland $ --> + +<html> + +<head> +<title>libgfx: Matrix Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Matrix Math</h2> + +<h3>class Mat3</h3> + +<p>This class implements a 3x3 real-valued matrix. +Individual elements are represented with <code>double</code> precision +floating point numbers. To use the <tt>Mat3</tt> class you must include the +header +<pre> + #include <gfx/mat3.h> +</pre> + +<h4>Constructor Methods</h4> + +<p>The <tt>Mat3</tt> class defines the following set of constructors: + +<pre> + <i>// Initialize all elements to 0</i> + Mat3(); + + <i>// Initialize rows with given vectors</i> + Mat3(const Vec3& r0,const Vec3& r1,const Vec3& r2); + + <i>// Copy values from A</i> + Mat3(const Mat3& A); +</pre> + + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/mat4.html b/debian/fireflies/fireflies-2.08/libgfx/doc/mat4.html new file mode 100644 index 00000000..d180d210 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/mat4.html @@ -0,0 +1,83 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: mat4.html 220 2001-01-16 21:21:46Z garland $ --> + +<html> + +<head> +<title>libgfx: Matrix Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Matrix Math</h2> + +<h3>class Mat4</h3> + + +<p>This class implements a 4x4 real-valued matrix. +Individual elements are represented with <code>double</code> precision +floating point numbers. To use the <tt>Mat4</tt> class you must include the +header +<pre> + #include <gfx/mat4.h> +</pre> + +<h4>Constructor Methods</h4> + +<p>The <tt>Mat4</tt> class defines the following set of constructors: + +<pre> + <i>// Initialize all elements to 0</i> + Mat4(); + + <i>// Initialize rows with given vectors</i> + Mat4(const Vec4& r0,const Vec4& r1,const Vec4& r2,const Vec4& r3); + + <i>// Copy values from A</i> + Mat4(const Mat4& A); +</pre> + + +<h4>Transformation Functions</h4> + +<p>Because 4x4 matrices are commonly used to represent linear homogeneous +transformations in computer graphics, the matrix package provides several +functions to construct transformation matrices. The operation of these +functions is based directly on the definition of the corresponding +transformations as used in OpenGL. The resulting matrices should be +equivalent to those produced by OpenGL, to the extent allowed by limited +floating point accuracy. + +<pre> + <i>// Construct translation, scaling, and rotation matrices.</i> + Mat4 translation_matrix(const Vec3& delta); + Mat4 scaling_matrix(const Vec3& scale); + Mat4 rotation_matrix_deg(double theta, const Vec3& axis); + Mat4 rotation_matrix_rad(double theta, const Vec3& axis); + + <i>// Construct a perspective projection matrix. + // Direct analog of gluPerspective()</i> + Mat4 perspective_matrix(double fovy, double aspect, + double zmin=0.0, double zmax=0.0); + + <i>// Construct a viewing transformation. + // Direct analog of gluLookAt()</i> + Mat4 lookat_matrix(const Vec3& from, const Vec3& at, const Vec3& up); + + <i>// Construct a viewport mapping. + // Direct analog of glViewport().</i> + Mat4 viewport_matrix(double w, double h); +</pre> + +Note that the <tt>rotation_matrix()</tt> function comes in two forms, once +which expects an angle in <em>radians</em> and one which expects an angle in +<em>degrees</em>. The type of angle expected is made explicit in the function +name (i.e., <tt>_rad</tt> and <tt>_deg</tt> suffixes) in an attempt to avoid +confusion. + + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/quat.html b/debian/fireflies/fireflies-2.08/libgfx/doc/quat.html new file mode 100644 index 00000000..781ed2ad --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/quat.html @@ -0,0 +1,113 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: quat.html 308 2002-03-11 21:16:57Z garland $ --> + +<html> + +<head> +<title>libgfx: Quaternions</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Quaternions</h2> + +<p>This package provides the basic mathematical tools necessary for +manipulating quaternions. To begin using it, you must first include the +header file: +<pre> + #include <gfx/quat.h> +</pre> + +<p>For more information on the definition of quaternions and their +associated mathematics, you might try the informative Web pages provided +by +<a href="http://mathworld.wolfram.com/Quaternion.html">MathWorld</a>, +<a href="http://www.magic-software.com/Documentation/quat.pdf">David + Eberly</a>, or +<a + href="http://graphics.cs.ucdavis.edu/GraphicsNotes/Quaternions.pdf">UC + Davis</a>. + +<h3>class Quat</h3> + +<p>The interface presented by the <tt>Quat</tt> class treats quaternions +as consisting of a real scalar part and a complex 3-vector part. + +<h4>Constructor Methods</h4> + +<p>The <tt>Quat</tt> class defines the following set of constructors: + +<pre> + Quat(); <i>// Initializes to identity quaternion</i> + Quat(double x, double y, double z, double w); <i>// Specify vector & scalar part.</i> + Quat(const Vec3& a, double b); <i>// Specify vector & scalar part.</i> + Quat(const Quat& q); <i>// Copy values from q</i> +</pre> + +<pre> + Quat::ident(); <i>// Return the identity quaternion</i> +</pre> + +<h4>Arithmetic Methods</h4> + +<p>The quaternion class supports all the usual arithmetic methods, both +as in-place assignment operators: + +<pre> + Quat& operator=(const Quat& q); + Quat& operator+=(const Quat& q); + Quat& operator-=(const Quat& q); + Quat& operator=(double d); + Quat& operator*=(double d); + Quat& operator/=(double d); +</pre> + +and as normal binary operations: + +<pre> + Quat operator+(const Quat& q, const Quat& r); + Quat operator*(const Quat& q, const Quat& r); + Quat operator*(const Quat& q, double s); + Quat operator*(double s, const Quat& q); + Quat operator/(const Quat& q, double s); +</pre> + +<h4>Quaternion Operations</h4> + +<p>Using the fundamental arithmetic operations defined above, this +package also provides the following operations on quaternions: +<pre> + double norm(const Quat& q); <i>// Return the length of q</i> + Quat conjugate(const Quat& q); <i>// Return conjugate of q</i> + Quat inverse(const Quat& q); <i>// Return multiplicative inverse of q</i> + void unitize(Quat& q); <i>// Convert to unit quaternion</i> + Quat exp(const Quat& q); <i>// Exponential of a <b>unit</b> quaternion </i> + Quat log(const Quat& q); <i>// Natural logarithm of a <b>unit</b> quaternion </i> +</pre> + +<p>Quaternions can be constructed from an axis/angle rotation +specification using the function: +<pre> + Quat axis_to_quat(const Vec3& a, double phi); +</pre> +At is also generally useful to be able to convert a quaternion into a +rotation matrix: +<pre> + Mat4 quat_to_matrix(const Quat& q); + Mat4 unit_quat_to_matrix(const Quat& q); +</pre> + +<p> +<pre> + Quat slerp(const Quat& from, const Quat& to, double t); +</pre> + +<p>Quaternions can also be read from and written to C++ iostreams using the +standard <tt><<</tt> and <tt>>></tt> operators. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/raster.html b/debian/fireflies/fireflies-2.08/libgfx/doc/raster.html new file mode 100644 index 00000000..544a30b6 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/raster.html @@ -0,0 +1,143 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: raster.html 157 2000-09-05 17:28:52Z garland $ --> + +<html> + +<head> +<title>libgfx: Raster Images</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Raster Images</h2> + +<p>The <tt>libgfx</tt> library provides very basic support for storing raster +image data. This is not really intended to provide the kind of support +necessary for advanced image processing, but rather the basic functionality +needed for saving screen snapshots, loading texture files, etc. To use this +package you will first need to include the header file +<pre> + #include <gfx/raster.h> +</pre> + +<h3>Image Representation</h3> + +<p>Images are implemented using the <tt>Raster<T></tt> template class. +The templated type <tt>T</tt> determines how individual pixel values are +stored. There are two standard image types: +<ul> +<li><tt>ByteRaster</tt>: +pixel components are represented with values of type <tt>unsigned +char</tt> + +<li><tt>FloatRaster</tt>: +pixel components are represented with values of type <tt>float</tt> +</ul> + +<h4>Allocating an Image</h4> + +<p>When allocating an image, you must specify its three dimensions: (1) width +in pixels, (2) height in pixels, and (3) number of channels. +<pre> + Raster<T>(int width, int height, int nchannels); +</pre> +Typically, the number of channels should by either 1 for grayscale images, 3 +for RGB color images, or 4 for RGB images with an alpha channel. + +<h4>Accessors</h4> + +<p>The dimensions of an image can be determined through a standard set of +accessor functions: +<pre> + int width(); <i>// Width of image (in pixels)</i> + int height(); <i>// Height of image (in pixels)</i> + int channels(); <i>// Number of channels in image</i> + int length(); <i>// Total number of pixel values</i> +</pre> +The width, height, and channel count values are merely those specified when +the image is allocated. The length of the image is the total number of pixel +elements (i.e., width*height*channels). + +<p>Pixel elements can be accessed in two different ways. First of all, you +can get a pointer to the single pixel at the image location (i,j) by calling +the method +<pre> + T *pixel(int i, int j); +</pre> +This is the standard way to access pixels. Alternatively, you can access +pixel elements using the standard C [] bracket notation. This method is +generally discouraged since it exposes the underlying layout of the image. +However, it can be useful if you want to visit every pixel element without +regard to its location. + + +<h4>Pixel Manipulation</h4> + +<p>The <tt>Raster</tt> template class provides some very simple methods for +manipulating the image which it stores. They are: +<pre> + void hflip(); <i>// Flip the image from left to right</i> + void vflip(); <i>// Flip the image from top to bottom</i> +</pre> + + +<h3>Input/Output of Image Files</h3> + +<p>In addition to internal image representation, this package provides a +simple set of functions for reading and writing external image files. +The library supports the following image types: +<ul> +<li>PNM (supported internally) +<li>TIFF (requires <a href="http://www.libtiff.org">libtiff</a>) +<li>JPEG (requires <a href="http://www.ijg.org">jpeglib</a>) +<li>PNG (requires <a href="http://www.libpng.org/pub/png/">libpng</a>) +</ul> + +<p>Images can be read from files using the following functions: +<pre> + ByteRaster *read_pnm_image(const char *filename); + ByteRaster *read_tiff_image(const char *filename); + ByteRaster *read_png_image(const char *filename); + ByteRaster *read_jpeg_image(const char *filename); +</pre> +These functions return <tt>NULL</tt> if the file could not be read. This +includes the case when the required external libraries are not available. +Similar functions can be used to write images to files: +<pre> + bool write_pnm_image(const char *filename, const ByteRaster&); + bool write_tiff_image(const char *filename, const ByteRaster&); + bool write_png_image(const char *filename, const ByteRaster&); + bool write_jpeg_image(const char *filename, const ByteRaster&); +</pre> +They return <tt>true</tt> or <tt>false</tt> indicating whether the output +operation succeeded or not. + +<p>The PNM output routines can output both raw (i.e., binary) and ASCII image +files. Which type of file they write is controlled by the global variable +<pre> + bool will_write_raw_pnm; +</pre> +Since JPEG is a lossy compression format, the behavior of the JPEG output +routines is dependent upon the global variable controlling image quality +<pre> + int jpeg_output_quality; +</pre> +These quality factors are integers ranging from 0-100 (with 100 being the +highest quality). See the <tt>jpeglib</tt> documentation for further details. + +<p>For convenience, you can read/write image files with the functions +<pre> + bool write_image(const char *filename, const ByteRaster&, int type=-1); + ByteRaster *read_image(const char *filename, int type=-1); +</pre> +The file format will be inferred from the filename, unless the optional +<tt>type</tt> argument is given. The image type should be one of +<tt>IMG_PNM</tt>, <tt>IMG_PNG</tt>, <tt>IMG_TIFF</tt>, or <tt>IMG_JPEG</tt>. + + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/rotate.html b/debian/fireflies/fireflies-2.08/libgfx/doc/rotate.html new file mode 100644 index 00000000..dc444409 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/rotate.html @@ -0,0 +1,107 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: rotate.html 309 2002-03-11 21:17:15Z garland $ --> + +<html> + +<head> +<title>libgfx: Interactive Rotation Control</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Interactive Rotation Control</h2> + +<p>The <tt>libgfx</tt> library provides a fairly simple facility for +interactive inspection of 3-D objects. The interface is designed +for applications where a user is inspecting an object by spinning it and +by translating the camera to provide a better view. All of the user +interaction is implemented through mouse motion: +<ul> + <li>Left mouse drag — rotate object about its centroid + <li>Right mouse drag — translate camera forward/backward + <li>Middle mouse drag — translate camera parallel to image plane +</ul> + +<p>The classes used to implement this functionality are based on a +fairly standard paradigm. Two subsequent mouse positions are projected +onto a notional surface "below" the window. The cross product of these +projected vectors defines an axis of rotation and the angle between them +defines the rotation angle. + +<h3>Ball Types</h3> + +<p>The library currently supports two control classes: + +<blockquote> + +<p><b>Arcball</b> The Arcball controller is based on the +article <i>Arcball Rotation Control</i> written by Ken Shoemake in +<i>Graphics Gems IV</i> published by Academic Press. +The underlying surface of projection is a hemisphere. + +<p><b>Trackball</b> Implements the mechanism used in the SGI +3-D demo programs. This approach was originally developed by Gavin +Bell. The underlying surface of projection is a hybrid of a hemisphere +and a hyperbolic sheet. +</blockquote> + +<h3>Public Interface</h3> + +<p>The two controller types both implement the same public interface, +and can be freely interchanged in the application program. The +interfaces for these controllers are defined in the following header +files: +<ul> + <li><tt>class Arcball</tt> — <tt><gfx/arcball.h></tt> + <li><tt>class Trackball</tt> — <tt><gfx/trackball.h></tt> +</ul> +To use one of the controllers, you need to include the appropriate +header and create an instance of the appropriate class. + +<h4>Initialization</h4> + +<p>Before using a rotation controller, you must initialize it by +providing the bounding sphere of the object to be controlled. This is +done using the templated method: +<pre> + template<class T> + void bounding_sphere(const TVec3<T>& center, T radius); +</pre> +The specified sphere <tt>center</tt> will be the point about which the +object will rotate. + +<h4>Interaction</h4> + +<p>Once initialized, the controller is meant to be interfaced directly +with the event handlers of an application built using the +<tt>libgfx</tt> <a href="gui.html">GUI framework</a>. +Each of the following controller methods should be called from the event +handlers of your application. +<pre> + virtual void update_animation(); + virtual bool mouse_down(int *where, int which); + virtual bool mouse_up(int *where, int which); + virtual bool mouse_drag(int *where, int *last, int which); +</pre> + +<h4>Applying Results</h4> + +<p>For the rotation to take effect, you must apply it in the rendering +loop of the application. Before drawing your scene, you should call the +method: +<pre> + virtual void apply_transform(); +</pre> +This will set up the appropriate transform on the <tt>ModelView</tt> +matrix stack. Similarly, when done drawing, you should call the method: +<pre> + virtual void unapply_transform(); +</pre> +which will clean up the <tt>ModelView</tt> matrix stack. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/script.html b/debian/fireflies/fireflies-2.08/libgfx/doc/script.html new file mode 100644 index 00000000..1a457b2d --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/script.html @@ -0,0 +1,192 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: script.html 269 2001-10-10 00:38:28Z garland $ --> + +<html> + +<head> +<title>libgfx: Simple File Format Scripting</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Simple File Format Scripting</h2> + +<p>The <tt>libgfx</tt> library provides a very simple scripting facility which +is primarily intended to support parsing of input files and control scripts. +To use this package, you must include the header file: +<pre> + #include <gfx/script.h> +</pre> + +<p>For more information about this package, you may want to examine the +sample <a href="ex-script.html">scripted application</a>. + +<h3>File Structure</h3> + +<p>Scripts processed by this package are assumed to be composed of a sequence +of lines. Each line is processed separately, in sequence, and falls into one +of the following categories: +<ol> +<li>Lines containing only whitespace are ignored +<li>Lines whose first non-whitespace character is a '#' (hash mark) are +treated as comments and are ignored +<li>All other lines are assumed to be a sequence of whitespace-separated +tokens where the first token is a command name and subsequent tokens are +arguments to this command. +</ol> + +<h3>Processing Scripts</h3> + +<p>In order to process scripts, you must (at minimum) perform the following +steps: +<ol> +<li>Instantiate a <i>scripting environment</i> of type <tt>CmdEnv</tt>. +<li>Register your command(s) with <tt>CmdEnv::register_command()</tt> +or <tt>CmdEnv::register_method()</tt>. +<li>Feed the text of the script to the parsing system. +</ol> +The specifics of these steps are detailed in the following sections. + +<h4>The Scripting Environment</h4> + +<p>The primary task of the scripting system is to map command name tokens into +command procedures. These procedures, also referred to as "handlers", are +responsible for actually performing the computation associated with a +particular command. +Handlers should conform to the following type definition: +<pre> + typedef int (*CmdHandler)(const CmdLine &cmd); +</pre> +The <tt>CmdLine</tt> type manages the text of a particular command line, and +provides various methods for parsing that information (see details below). + +<p>The <tt>CmdEnv</tt> class manages the mapping of command names to +handlers. In particular, handler names are mapped to pointers to +objects derived from the base class <tt>CmdObject</tt>. All derived +classes of <tt>CmdObject</tt> are required to override the +<tt>operator()</tt> invocation virtual method. By using this virtual +function, handler objects are allowed to encapsulate arbitrary data in +their definition (i.e., to create closures). The standard scripting +framework defines two kinds of <tt>CmdObject</tt> handlers: (1) the +<tt>CmdFunction</tt> class to encapsulate normal functions and static +methods and (2) and the <tt>CmdMethod</tt> template class to +encapsulate member functions. + + +<p>New handler procedures (non-member functions) +can be associated with names using +the method: +<pre> + void register_command(const std::string& name, CmdHandler proc); +</pre> +Member functions can be bound to names uses the templated member +function: +<pre> + template<class T> + void register_method(const std::string& name, + T *obj, + int (T::*fn)(const CmdLine&)); +</pre> +Note that in both cases, prior bindings of <tt>name</tt> associated +with another handler will be overwritten. +Existing handlers can be located by name +using the method: +<pre> + CmdObject *lookup_command(const std::string& name); +</pre> +which returns <tt>NULL</tt> if no handler is bound to the given name. + +<h4>Submitting Text for Execution</h4> + +<p>Several procedures are available for submitting script text to the parsing +system. All of them require a <tt>CmdEnv</tt> argument that will determine +the mapping of command names to handlers. + +<p>The underlying method for parsing text is: +<pre> + int script_do_line(std::string &line, CmdEnv &env); + int script_do_line(const char *line, CmdEnv &env); +</pre> +It assumes that its input is a string consisting of a single line — any +embedded newlines will be treated like any other whitespace. +It will +split this line it a series of whitespace-separated tokens, interpreting the +first such token as a command name. If <tt>env</tt> provides a binding for +this name, the appropriate handler will be called. + +<p>For convenience, the scripting package also provides the following methods: +<pre> + int script_do_stream(std::istream &in, CmdEnv &env); + int script_do_file(const char *name, CmdEnv &env); + int script_do_string(const char *str, CmdEnv &env); +</pre> +They operate by extracting a single line from the input source and processing +that line with <tt>script_do_line()</tt>. They repeat this line-by-line +process until the file/stream/string has been exhausted. +The first time the processing of a line fails with an error code, these +procedures return this error code immediately without completing the +processing of the rest of the input. + + +<h3>Writing Command Handlers</h3> + +<p>A command procedure is declared as follows: +<pre> + int proc(const CmdLine& cmd); +</pre> +The <tt>CmdLine</tt> structure contains all the necessary data about the line +being processed. It provides the following fundamental accessors: +<pre> + class CmdLine + { + public: + const std::string &line; // Raw text of the (complete) line + std::string opname() const; // Name of the command being invoked + std::string argline() const; // Argument string + int argcount() const; // Number of argument tokens + }; +</pre> +The argument string returned by <tt>argline()</tt> is unparsed except that +whitespace following the command name and trailing whitespace at the end of +the line have been removed. + + +<p>It is up to the handler to parse the command line in whatever way it likes. +However, the scripting system assumes that command will be given +whitespace-separated token lists. Therefore, it pre-computes the indices of +these tokens in the command line text before invoking the handler. To access +an individual token, you can use the <tt>CmdLine</tt> methods: +<pre> + std::string token_to_string(int i) const; + double token_to_double(int i) const; + float token_to_float(int i) const; + int token_to_int(int i) const; +</pre> +Tokens are numbered from <tt>[0 .. argcount()-1]</tt>. Note that, for +efficiency, these methods <em>do not perform range checking.</em> It is up to +the caller to verify that the given indices are valid. + +<p>In addition to accessing single argument tokens, you can collect all +argument tokens into lists with the following <tt>CmdLine</tt> methods: +<pre> + int collect_as_strings(std::vector<std::string> &v) const; + int collect_as_numbers(std::vector<double> &v) const; + int collect_as_numbers(std::vector<int> &v) const; + + int collect_as_numbers(double *v, int size) const; + int collect_as_numbers(float *v, int size) const; + int collect_as_numbers(int *v, int size) const; +</pre> +These methods always return the number of tokens collected. +The <tt>vector</tt>-based methods will always collect all available tokens. +In contrast, those which accept raw arrays will either collect <tt>size</tt> +or <tt>argcount()</tt> tokens, whichever is smaller. + +<p>See the accompanying <a href="ex-script.html">scripting example</a> for more +details on how to write command handlers. + +</body> +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/start.html b/debian/fireflies/fireflies-2.08/libgfx/doc/start.html new file mode 100644 index 00000000..75da67d6 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/start.html @@ -0,0 +1,136 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: start.html 111 2000-07-31 21:40:02Z garland $ --> + +<html> + +<head> +<title>libgfx: Getting Started</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Getting Started </h2> + +<p>The <tt>libgfx</tt> library can be used for writing both +console-oriented and GUI programs. All programs, whether console or +GUI, should begin by including the standard header: +<pre> + #include <gfx/gfx.h> +</pre> + +<h3>The Standard Header: gfx.h</h3> + +<p>The first task of the standard header file is to provide a consist +code environment. It begins by including a set of standard C++ +headers <tt><cstdlib></tt>, <tt><cmath></tt>, +<tt><climits></tt>, and <tt><iostream></tt>. +It then makes sure that various common symbols, such as <tt>bool</tt>, +<tt>M_PI</tt>, and <tt>HUGE</tt> are defined. + +<h4>Numerical Procedures</h4> + +<p>Graphics programs typically involve a substantial amount of +mathematical calculation. Indeed, much the the <tt>libgfx</tt> +library is devoted to supporting things such as matrix/vector +computations. Certain mathematical procedures are common enough, and +simple enough, that they are included in the standard header. + +<p>First, there are the procedures for generating random numbers: +<pre> + inline double random1(); <i>// Random number between 0 and 1</i> + inline char random_byte(); <i>// Random byte between 0 and 255</i> +</pre> +These functions use the internal <tt>random()</tt> procedure if it's +available, or <tt>rand()</tt> if not. + +<p>Next, are procedures for comparing floating point numbers: +<pre> + const double FEQ_EPS = 1e-6; + const double FEQ_EPS2 = 1e-12; + + inline bool FEQ(double a, double b, double eps=FEQ_EPS); + inline bool FEQ2(double a, double b, double eps=FEQ_EPS2); +</pre> +The <tt>FEQ()</tt> procedures return <tt>true</tt> if <tt>a</tt> and +<tt>b</tt> are within <tt>eps</tt> of each other. + +<h4>Timing Procedures</h4> + +<p>To characterize the performance of a program, it is often useful to +measure it's running time. For this reason, <tt>libgfx</tt> provides +some basic facilities for measuring time. + +<pre> + extern double get_cpu_time(); +</pre> + +The function returns the number of seconds on the CPU clock. Based on +the platform you're using, this function may use various system +services to compute this clock. Therefore, it does not use a +consistent measure across all systems; however, the returned quantity +will usually be the number of seconds since the system was turned on. + +<p>A more convenient way to measure running time is to use the +following macro: +<pre> + #define TIMING(t, cmd) { t=get_cpu_time(); cmd; t=get_cpu_time() - t; } +</pre> +Given a procedure <tt>test_proc()</tt> whose performance we want to +measure, we can use the following code: +<pre> + double running_time; + + TIME(running_time, test_proc()); + + cout << "The running time was: " << running_time << " seconds." << endl; +</pre> +This will print the running time of <tt>test_proc()</tt> on the console. + + +<h4>Configuration Definitions</h4> + +<p>The final task of the standard header is to include the +<tt>libgfx</tt> configuration header. This header is generated when +the library is compiled. On Unix-like platforms, the header is named +<tt><gfx/config.h></tt> and is generated automatically by the +configuration script. For Microsoft Visual Studio platforms, a +hand-coded header such as <tt><gfx/config-vc5.h></tt> is used +instead. The symbols defined in this header can be used to detect the +presence of various language features and external libraries. +The symbols of interest to external programs are summarized below: + +<br><br> +<table align=center width=85% border=0 cellpadding=5> +<tr valign=top><th align=left>Symbol</th><th align=left>Defined when ...</th></tr> + +<tr valign=top><td><tt>HAVE_LIBTIFF</tt></td> +<td>library supporting TIFF image I/O is available.</td></tr> + +<tr valign=top><td><tt>HAVE_LIBTIFF_LZW</tt></td> +<td><tt>libtiff</tt> supports patented LZW compression.</td></tr> + +<tr valign=top><td><tt>HAVE_LIBPNG</tt></td> +<td>library supporting PNG image I/O is available.</td></tr> + +<tr valign=top><td><tt>HAVE_LIBJPEG</tt></td> +<td>library supporting JPEG image I/O is available.</td></tr> + +<tr valign=top><td><tt>HAVE_OPENGL</tt></td> +<td>OpenGL is available. Value is name of implementation +(e.g., "OpenGL" or "Mesa").</td></tr> +</table> + +<p>These configuration symbols should be tested with <tt>#ifdef</tt> +directives, as in the following example: +<pre> + #ifdef HAVE_LIBTIFF + generate_tiff_output(); + #endif +</pre> + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/vec.html b/debian/fireflies/fireflies-2.08/libgfx/doc/vec.html new file mode 100644 index 00000000..f62aa29d --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/vec.html @@ -0,0 +1,125 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: vec.html 289 2002-01-14 18:21:43Z garland $ --> + +<html> + +<head> +<title>libgfx: Vector Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Vector Math</h2> + +<p>The <tt>libgfx</tt> vector math package provides classes that +make it much more convenient to write vector equations. +Two dimensional [<a href="vec2.html">Vec2</a>], +three dimensional [<a href="vec3.html">Vec3</a>], +and four dimensional [<a href="vec4.html">Vec4</a>] +vector classes are provided. + +<p>A vector consists of <i>n</i> numeric values. These vector types are +actually implemented using template classes such as <tt>TVec3<class +T></tt> that allow the application to specify the type of value used to +represent the vector elements. The standard classes described in this +documentation (<tt>Vec2</tt>, <tt>Vec3</tt>, and <tt>Vec4</tt>) use double +precision floating point values. Corresponding classes using single precision +floating point values (<tt>Vec2f</tt>, <tt>Vec3f</tt>, and <tt>Vec4f</tt>) are +also provided. + +<p>The elements of a vector are accessed with the standard bracket notation +used for arrays. And like C++ arrays, vectors are indexed starting from 0. +Thus the elements of a 3-vector can be assigned as follows: + +<pre> + Vec3 v; + + v[0] = 1.0; + v[1] = 0.0; + v[2] = 2.0; +</pre> + +The default constructors (as used in the previous example) always +initialize the vector elements to 0. All vector classes also provide +constructors which accept the initial element values as arguments. +Thus the previous example could be more succinctly written as: + +<pre> + Vec3 v(1.0, 0.0, 2.0); +</pre> + +Vectors can also be automatically cast to <code>double</code> pointer +types. Continuing the preceding example, the following is perfectly legal: +<pre> + double *w = v; <i>// w points to the first element of v</i> + w[1] = 3.14; <i>// Exactly equivalent to v[1] = 3.14</i> +</pre> + +<p><strong>Warning:</strong> +For efficiency reasons, <em>accessors are not range checked</em>. +Thus you can legally write + +<pre> + Vec3 v; + v[42] = 3.14159; +</pre> + +and this will cause an invalid memory access beyond the bounds of the +vector. This may cause a memory fault or it may just silently +over-write other data. Therefore you must make sure that you only +access valid elements of arrays. + + +<h3>Arithmetic Operators</h3> + +<p>One of the primary goals of the vector package is to simplify the +coding of vector equations. To accomplish this, it makes use of +<em>operator overloading</em>. + + +<p><strong>Assignment</strong> +Vectors can be assigned the values of other vectors or scalars. +A vector assignment <tt>v = w</tt> copies the elements of <tt>w</tt> +into the corresponding elements of <tt>v</tt>. A scalar assignment +<tt>v = 1.0</tt> copies the given scalar, in this case <tt>1.0</tt>, +into each of the elements of <tt>v</tt>. + +<p><strong>Addition/Subtraction</strong> Vectors can be +added together either with the binary addition operator (<tt>u = v + +w</tt>) or the additive assignment operator (<tt>u += v</tt>). +Subtraction operates similarly, using subtraction rather than addition +operators. + +<p><strong>Scalar Multiplication/Division</strong> +Vectors can be multiplied by scalar values using either the binary +operator (<tt>v * 2.0</tt>) or the accumulation operator (<tt>v *= +2.0</tt>). Scalar division operates similarly. + +<p><strong>Inner Product</strong> +The inner product (or dot product) of two vectors is written with the +standard multiplication operator: <tt>v * w</tt>. + +<h3>Standard Vector Functions</h3> + +<p>All vector classes support a standard set of functions for +performing common operations on vectors. These functions are: +<pre> + <i>// Returns the squared length of the vector v</i> + inline double norm2(const Vec_& v); + + <i>// Returns the length of the vector v</i> + inline double norm(const Vec_& v); + + <i>// Adjusts v to have unit length. Mostly equivalent to v/=norm(v)</i> + inline void unitize(Vec_& v); +</pre> + +<p>Vector can also be read from and written to C++ iostreams using the +standard <tt><<</tt> and <tt>>></tt> operators. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/vec2.html b/debian/fireflies/fireflies-2.08/libgfx/doc/vec2.html new file mode 100644 index 00000000..5faa016a --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/vec2.html @@ -0,0 +1,52 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: vec2.html 153 2000-09-05 16:11:26Z garland $ --> + +<html> + +<head> +<title>libgfx: Vector Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Vector Math</h2> + +<h3>class Vec2</h3> + +<p> This class implements a 2-dimensional real-valued vector. +Individual elements are represent with <code>double</code> precision +floating point numbers. To use the <tt>Vec2</tt> class you must +include the header +<pre> + #include <gfx/vec2.h> +</pre> + +<h4>Constructor Methods</h4> + +<p>The <tt>Vec2</tt> class defines the following set of constructors: + +<pre> + Vec2(); <i>// Initializes vector to (0 0).</i> + Vec2(double x, double y); <i>// Initializes vector to (x y).</i> + Vec2(double s); <i>// Initializes vector to (s s)</i> + + Vec2(const Vec2& v); <i>// </i> + Vec2(const float v[2]); <i>// These copy values from v</i> + Vec2(const double v[2]); <i>// </i> +</pre> + +<h4>Specialized Functions</h4> + +<p>Beyond the standard functions supported by all vector classes, the +<tt>Vec2</tt> class provides the following additional function: +<pre> + Vec2 perp(const Vec2 &v); +</pre> +that returns a new vector which is perpendicular to the given vector. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/vec3.html b/debian/fireflies/fireflies-2.08/libgfx/doc/vec3.html new file mode 100644 index 00000000..83e27c60 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/vec3.html @@ -0,0 +1,70 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: vec3.html 86 2000-06-13 18:59:13Z garland $ --> + +<html> + +<head> +<title>libgfx: Vector Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Vector Math</h2> + +<h3>class Vec3</h3> + +<p> This class implements a 3-dimensional real-valued vector. +Individual elements are represent with <code>double</code> precision +floating point numbers. To use the <tt>Vec3</tt> class you must +include the header +<pre> + #include <gfx/vec3.h> +</pre> + +<h4>Constructor Methods</h4> + +<p>The <tt>Vec3</tt> class defines the following set of constructors: + +<pre> + Vec3(); <i>// Initializes vector to (0 0 0).</i> + Vec3(double x, double y, double z); <i>// Initializes vector to (x y z).</i> + Vec3(double s); <i>// Initializes vector to (s s s)</i> + + Vec3(const Vec3& v); <i>// </i> + Vec3(const float v[3]); <i>// These copy values from v</i> + Vec3(const double v[3]); <i>// </i> + + Vec3(const Vec2& v, double z); <i>// Initializes vector to (v[0] v[1] z)</i> +</pre> + +<h4>Specialized Functions</h4> + +<p>In addition to the standard functions provided by all vector classes, +the <tt>Vec3</tt> class defines certain specialized functions which +operate only on 3-D vectors. + +<p>The <em>cross product</em> of two vectors <tt>v, w</tt> is a third +vector which is perpendicular to both <tt>v</tt> and <tt>w</tt>. +It can be computed with either a function call or an overloaded +operator + +<pre> + u = cross(v, w); <i>// Equivalent ways of computing</i> + u = v ^ w; <i>// the cross product of v and w.</i> +</pre> + +<p>Since 3-D vectors may be used to represent 2-D homogeneous +coordinates, a projection function is provided. +<pre> + Vec2 proj(const Vec3& v); +</pre> +This routine takes a homogeneous vector <i>(x y w)</i> and returns the +corresponding 2-D vector <i>(x/w y/w)</i>. If <i>w</i> is 0 then +the vector <i>(x y)</i> is returned. + +</body> + +</html> diff --git a/debian/fireflies/fireflies-2.08/libgfx/doc/vec4.html b/debian/fireflies/fireflies-2.08/libgfx/doc/vec4.html new file mode 100644 index 00000000..77e3e467 --- /dev/null +++ b/debian/fireflies/fireflies-2.08/libgfx/doc/vec4.html @@ -0,0 +1,65 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<!-- $Id: vec4.html 86 2000-06-13 18:59:13Z garland $ --> + +<html> + +<head> +<title>libgfx: Vector Math</title> +<link rel=stylesheet href="cdoc.css" type="text/css"> +<meta name="Author" content="Michael Garland"> +</head> + +<body> + +<h2>Vector Math</h2> + +<h3>class Vec4</h3> + +<p> This class implements a 4-dimensional real-valued vector. +Individual elements are represent with <code>double</code> precision +floating point numbers. To use the <tt>Vec4</tt> class you must +include the header +<pre> + #include <gfx/vec4.h> +</pre> + +<h4>Constructor Methods</h4> + +<p>The <tt>Vec4</tt> class defines the following set of constructors: + +<pre> + Vec4(); <i>// Initializes vector to (0 0 0 0).</i> + Vec4(double x, double y, double z, double w); <i>// Initializes vector to (x y z w).</i> + Vec3(double s); <i>// Initializes vector to (s s s s)</i> + + Vec4(const Vec4& v); <i>// </i> + Vec4(const float v[4]); <i>// These copy values from v</i> + Vec4(const double v[4]); <i>// </i> + + Vec4(const Vec3& v, double w); <i>// Initializes vector to (v[0] v[1] v[2] w)</i> +</pre> + +<h4>Specialized Functions</h4> + +<p>In addition to the standard functions provided by all vector classes, +the <tt>Vec4</tt> class defines certain specialized functions which +operate only on 4-D vectors. + +<p>The <em>cross product</em> of three 4-vectors <tt>u, v, w</tt> is a +fourth vector which is perpendicular to all of <tt>u, v, w</tt>. +It can be computed with the function call + +<pre> + t = cross(u, v, w); +</pre> + +<p>Since 4-D vectors are frequently +used to represent 3-D homogeneous +coordinates, a projection function is provided. +<pre> + Vec3 proj(const Vec4& v); +</pre> +This routine takes a homogeneous vector <i>(x y z w)</i> and returns the +corresponding 3-vector <i>(x/w y/w z/w)</i>. If <i>w</i> is 0 then +the vector <i>(x y z)</i> is returned. |
