Added documents.

git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@10 7f0cb862-5218-0410-a997-914c9d46530a
This commit is contained in:
sjbaker 2001-07-27 07:22:53 +00:00
parent 972665c820
commit 84e04ed9f0
8 changed files with 530 additions and 0 deletions

7
.gitattributes vendored
View File

@ -10,6 +10,13 @@ freeglut/freeglut/TODO svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/acconfig.h svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/aclocal.m4 svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/configure.in svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/doc/download.html svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/doc/freeglut.html svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/doc/freeglut_logo.png -text
freeglut/freeglut/doc/index.html svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/doc/ogl_sm.png -text
freeglut/freeglut/doc/progress.html svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/doc/structure.html svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/freeglut-1.3/.deps/freeglut_callbacks.P svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/freeglut-1.3/.deps/freeglut_cursor.P svn_keywords=Author+Date+Id+Revision
freeglut/freeglut/freeglut-1.3/.deps/freeglut_display.P svn_keywords=Author+Date+Id+Revision

View File

@ -0,0 +1,42 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="author" content="Pawel W. Olszta">
<meta name="copyright" content="Pawel W. Olszta">
<meta name="description" content="The downloads page">
<meta name="keywords" content="freeglut glut OpenGL">
<meta name="GENERATOR" content="WebMaker">
<title>The freeglut project</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<center><img SRC="freeglut_logo.png" ALT="The freeglut logo" height=106 width=314></center>
<center><dt><i><font face="Courier New,Courier"><font size=+1>
I upload it, you download it. That's the ying-yang nature of the Buddha.
</font></font></i></dt></center>
<center><table WIDTH="620"><tr><td><hr WIDTH="100%">
<p><i>January the 16th, 2000</i>
<p>Here is a list of files you can download:
<p>
<ul>
<li>
<a href="freeglut-1.3-alpha-2000-01-04.tar.gz">
freeglut-1.3-alpha-2000-01-04.tar.gz</a> (approx. 210kB)
<li>
<a href="freeglut-1.3-alpha-2000-01-06.tar.gz">
freeglut-1.3-alpha-2000-01-06.tar.gz</a> (approx. 220kB)
<li>
<a href="freeglut-1.3-alpha-2000-01-09.tar.gz">
freeglut-1.3-alpha-2000-01-09.tar.gz</a> (approx. 230kB)
<li>
<a href="freeglut-1.3-alpha-2000-01-16.tar.gz">
freeglut-1.3-alpha-2000-01-16.tar.gz</a> (approx. 230kB)
</ul>
</table></center></body></html>

View File

@ -0,0 +1,163 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="author" content="Pawel W. Olszta">
<meta name="copyright" content="Pawel W. Olszta">
<meta name="description" content="A bit about me and the freeglut project">
<meta name="keywords" content="freeglut glut OpenGL">
<meta name="GENERATOR" content="WebMaker">
<title>The freeglut project</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<center><img SRC="freeglut_logo.png" ALT="The freeglut logo" height=106 width=314></center>
<center><dt><i><font face="Courier New,Courier"><font size=+1>
I am best at what I do worst and for this gift I feel blessed...
</font></font></i></dt></center>
<center><table WIDTH="620"><tr><td><hr WIDTH="100%">
<p><i>January the 2nd, 2000</i>
<p>The alpha version has been released yesterday. Today I have been busy with moving
the project site to the <a href="http://www.sourceforge.net">SourceForge</a>. As for
now there will be the web site available and I will give it a try to set up the
freeglut mailing lists. There will be no CVS access available for now (my dialup
internet connection sucks so badly that I wouldn't be able to work on the project).
After I am done with that, I will try announcing the project on www.opengl.org.
<p>Of other things, there has been rumours floating round the routers and hubs about
Mark Kilgard changing the GLUT's license, but this is unconfirmed. It would be really
cool if he did so, there's no better motivation to work than a bit of sound competition.
As for me, I already put too much work into the freeglut project to terminate it just
now. We'll see what happens next.
<p><i>January the 4th, 2000</i>
<p>Ho-ho-ho. Freeglut-1.3 works fine with `Tux the Penguin and the Quest for Herring'.
At least that's what Steve Baker, the author, says. Not only that, Steve has provided
us with the joystick code (from his great PLIB project) and numerous hints and tips
about making freeglut more useful (I will try to put the results of our discussion
on the <a href="structure.html">structure page</a>).
<p>As for other issues -- I promise I will start the Win32 port this weekend.
BTW. -- is there a decent cross compiler for Linux that generates Win32 executables,
so that I don't have to use windows for development? And what about Wine OpenGL
support?
<p>The package is now some 40kB smaller than the previous one. Did some general
clean ups, removed unnecessary configure scripts in the genfonts directory,
the configure cahce, the Makefiles and so on. Also, I have started introducing
the new internal structure, as described <a href="structure.html">here</a>.
<p><i>January the 6th, 2000</i>
<p>The missing glutInit() issue seems to be solved. Chris Purnell (fxGLUT author) says
that the GLUT window and menu creation functions call glutInit() if the caller didn't
do that before.
<p>The enumerations for GLUT_KEY_UP and GLUT_KEY_RIGHT were accidentally swapped.
They should be OK now. Hope the rest is OK :)
<p>Added two new API calls to freeglut-1.3 -- glutBitmapHeight() and glutStrokeHeight(),
as suggested by Steve Baker. This won't break the GLUT compatibility a lot, and I've
heard it can be useful. Here you go.
<p>The <a href="structure.html">structure</a> plans page has been updated. The numerous
feature hints from opengl-gamedev-l readers have been added.
<p>Somebody (Chris?) hinted me that the stroke fonts can be found in the XFree86
sources. I browsed through it and -- presto. Now I only need to define the stroke fonts
structure (should be very similiar to bitmapped one) and write quite a simple parser.
<p>I've spent the (late) evening doing the init display string parsing and making
my logics classes homework :) Both is harder than I primarily thought, but fortunately
for me I can commit errors in one of those tasks. Guess which one? Argh. :)
<p><i>January the 8th, 2000</i>
<p>First of all, both the missing glutInit() and glutGet(GLUT_WINDOW_[X|Y]) issues are
fixed now. The first problem was solved thanks to Chris Purnell, who showed me the way
GLUT dealt with the problem. Good for me there's someone who reads it's source code (I
just felt it would be unfair for me to do so :D). The second problem was solved by
adding a XMoveWindow call just after the window creation and initial mapping. This is
strange. Maybe one of the Xlib calls between the creation and mapping spoiled the
window's coordinates?
<p>This makes even more GLUT tests work fine. The tests can be found in any decent
GLUT 3.7 distribution. Following tests produce a FAIL message: test18.c (some layer
issues), test19.c (see the GLUT_NORMAL_DAMAGED issue on the progress page), test22.c
(window stacking/visibilty problems), test23.c (glutInitDisplayString() is unfinished),
test25.c (the freeglut fonts differ a bit from GLUT's), test28.c (-iconic handling
is missing(?)). Gee :)
<p>I've spent another hour doing the glutInitDisplayString(), but it still is far from
being complete. And I've also started gathering information on doing the game mode
stuff. The video mode enumeration in both cases will be painful.
<p>There is a big issue with the window contents redrawing. Right now, it is forced
every time there are no events pending in the main loop. I know it's wrong, but it
without such an approach some of the test programs freeze soon after starting. Could
someone peer-review the main loop code please?
<p>I have decided to start the Win32 port this weekend. As for now, the code compiles
under vc++5.0. I will start making it work as soon as I download the pthreads library
and the newest version of GLib for Windows. It was quite a good idea to start the port,
as the Microsoft's compiler generates much more warnings and I had quite a few things
fixed for free.
<p><i>January the 9th, 2000</i>
<p>Doing the Win32 port all the day... Actually, there is enough code to make it work,
however I am sure only of that it compiles (more or less). I need to download the
pthreads-win32 library to get the GLib working first, and somehow I was unable to
do it during the weekend. Once again -- the Win32 port does not work yet. Oh, and
I need adding the __declspec(dllexport) thing...
<p>After it starts working, I'll have to clean up the code a bit, I guess...
<p><i>January the 10th, 2000</i>
<p>Here I am at three o'clock am, half-awake, uploading and downloading things for
freeglut. I never thought I'd be able to force myself getting up that early :)
<p><i>January the 16th, 2000</i>
<p>Both the flu and a terrible feeling about the dialup bills made me slow down
a bit, the internet activity I mean :). But here I am again uploading the latest
snapshot. The biggest news about it is the Win32 port working, with nearly all
features you can find in the X11 version implemented (still, it needs some debugging).
For the Unix port, game mode support (loosely based on SDL source code posted at Neal
Tringham's www.pseudonymz.demon.co.uk) and numerous bug fixes have been introduced.
<p>In order to compile the Win32 version, you'll need pthreads-win32 library (see
sourceware.cygnus.org), the GLib-1.2.x (www.gtk.org, I've been using the 1.2.6),
a working native compiler (Microsoft VisualC++ 5.0 in my case), and a bit of patience.
See the project files I've supplied for some definitions needed (FREEGLUT_LIBRARY_BUILD
needs to be declared when building the DLL), and don't forget freeglut joystick code
is making use of Win32 multimedia extensions (link against winmm.lib).
<p>Be prepared to meet the fact Mesa 3.1 (or at least my compilation) doesn't work very
well with this snapshot -- something's messed up when changing WGL contexts. This is
really strange, as the Microsoft's OpenGL works pretty fine, as does Dominik Behr's
miniGL thing. The assumption is that I've taken some approach that somehow is valid
with Microsoft's drivers, but is not OpenGL conformant. Could anyone check this out
please?
<p>My plan for next week is to add some lesser features missing, and start learning
maths as the session at my university is coming in really fast :) This way or another,
expect the next release not any sooner than next weekend (given that no nasty bugs get
digged out).
<p>Argh. Don't be surprised if the code doesn't compile under X-11 other than XFree86.
It could fail when trying to include the X11/extensions/xf86vmode.h include header,
in that case just comment out that inclusion line (found in freeglut_internal.h).
Is there any intelligent way to detect the existence of an include header, and if
it's autoconf to be the answer, how to use it?
<br><br><a href="index.html"><i>Back to the main page</i></a>
</table></center></body></html>

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

101
freeglut/freeglut/doc/index.html Executable file
View File

@ -0,0 +1,101 @@
<html>
<head>
<title>The freeglut project</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<table>
<tr>
<td>
<center><img SRC="freeglut_logo.png" ALT="The freeglut logo"></center>
<center><i><font size=+1> The free OpenGL utility toolkit </font></i></center>
</td>
<td>
<center><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=0&type=1" border="0">
</a></center><br>
<center><i>Hosted at SourceForge</i></center>
</td>
</tr>
</table>
<hr>
<ul>
<li><b><font size=+2>What</font></b>
<p>
freeglut is a completely OpenSourced alternative to the OpenGL Utility
Toolkit (GLUT) library. GLUT was originally written by Mark Kilgard
to support the sample programs in the second edition OpenGL 'RedBook'.
Since then, GLUT has been used in a wide variety of practical applications
because it is simple, universally available and highly portable.
<p>
GLUT (and hence freeglut) allows the user to create and manage
windows containing OpenGL contexts on a wide range of platforms and
also read the mouse, keyboard and joystick functions.
<p>
freeglut is released under the X-Consortium license.
<p>
<li><b><font size=+2>Why</font></b>
<p>
The original GLUT library seems to have been abandoned with the most
recent version (3.7) dating back to August 1998. It's license does
not allow anyone to distribute modified the library code. This would
be OK, if not for the fact that GLUT is getting old and really needs
improvement. Also, GLUT's license is incompatible with some software
distributions (eg Xfree86).
<p>
<li><b><font size=+2>Who</font></b>
<p>
freeglut was originally written by Pawel W. Olszta with contributions
from Andreas Umbach and Steve Baker. Steve is now the official
owner/maintainer of freeglut.
<p>
<li><b><font size=+2>When</font></b>
<p>
Pawel started freeglut development on December 1st, 1999.
The project is now a virtually 100% replacement for the original
GLUT with only a few departures (such as the abandonment of SGI-specific
features such as the Dials&Buttons box and Dynamic Video Resolution).
<p>
<li><b><font size=+2>Downloads</font></b>
<p>
Check the <a href="download.html">
downloads page</a> for the latest release.
<p>
<li><b><font size=+2>Support</font></b>
<p>
Send freeglut related questions to the appropriate freeglut mailing list:
<ul>
<li><a href="mailto:freeglut-developer@lists.sourceforge.net">freeglut-developer</a>,
<li><a href="mailto:freeglut-announce@lists.sourceforge.net">freeglut-announce</a> and
<li><a href="mailto:freeglut-bugs@lists.sourceforge.net">freeglut-bugs</a>.
</ul>
You can subscribe to them via the
<a href="http://sourceforge.net/project/?group_id=1032">
SourceForge project interface</a>.
<p>
<li><b><font size=+2>Documentation</font></b>
<p>
I believe this is enough for a short introduction.
If you are not tired of reading yet, check out the
<a href="freeglut.html">freeglut project log</a>. Here you will find the
yet-to-be-introduced new project <a href="structure.html">structure
description</a>. Finally, here you will find the latest
<a href="progress.html">work progress report</a>. Since freeglut is
a re-implementation of the original GLUT API, you can find API
documentation at <A HREF="http://www.opengl.org">http://www.opengl.org</A>.
<p>
</ul>
</body></html>

BIN
freeglut/freeglut/doc/ogl_sm.png Executable file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.5 KiB

View File

@ -0,0 +1,137 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="author" content="Pawel W. Olszta">
<meta name="copyright" content="Pawel W. Olszta">
<meta name="description" content="The freeglut development progress reports">
<meta name="keywords" content="freeglut glut OpenGL">
<meta name="GENERATOR" content="WebMaker">
<title>The freeglut project</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<center><img SRC="freeglut_logo.png" ALT="The freeglut logo" height=106 width=314></center>
<center><dt><i><font face="Courier New,Courier"><font size=+1>
I love reports. They are so full of brightness and hope...
</font></font></i></dt></center>
<center><table WIDTH="620" ><tr><td><hr WIDTH="100%">
<p><i>January the 16th, 2000</i>
<p>It looks like both X11 and Win32 version have reached a comparable usability stage.
They are still missing many GLUT API 3 features, but the number is getting smaller and
smaller every day :)
<br><ul><li><b><font size=+2>input devices</font></b></li>
<p>Keyboard and mouse seems to work well. There is a big guess about the mouse buttons
count under X11 (always 3) -- I must remember to correct the menu activation code if
this shows to be invalid.
<p>None of the bizarre input devices found in GLUT API is supported (and probably won't).
<p>Steve Baker contributed the joystick code. It should work fine, as it did in PLIB,
but I haven't tested it out yet. It might not compile under FreeBSD, as I had to
convert it from C++ to C and had no possibility to compile it under FreeBSD (the Win32
version had some typos, but I've already fixed them).
<br><br><li><b><font size=+2>pull-down menus</font></b></li>
<p>Pull down menus seem to work. The menu is displayed using OpenGL, so it requires
the window's contents to be refreshed at an interactive rate, which sometimes does not
happen. That's why I'll consider adding optional window-system menu navigation later.
For now -- extensive testing is what I believe should be done with the menu system.
<br><br><li><b><font size=+2>fonts</font></b></li>
<p>Bitmap fonts support is done. However it would be good to add two more API functions
-- glutBitmapString() and glutStrokeString(), which should limit the quantity of state
changes when drawing longer strings.
<p>Good that somebody finally told me where to get the stroke fonts data from... XFree86
sources contain the ROMAN and MONO ROMAN stroke fonts data. For now stroke fonts are
rendered using the bitmap font GLUT_BITMAP_8_BY_13.
<p>What has changed is the way the fonts are specified. I moved to the GLUT's strange
way of supplying (fake for freeglut) font data pointers instead of some nice enums.
Hope it helps in achieving the binary compatibility between freeglut and GLUT.
<p>Added two new API calls: glutBitmapHeight() and glutStrokeHeight(), that return
a font's height. Hope this doesn't break the GLUT compatibility a lot.
<br><br><li><b><font size=+2>mouse cursor</font></b></li>
<p>Need to have own cursor shapes, so that freeglut can pass them to the windowing
system, draw them using glBitmap() and/or texture mapping. The cursor shapes are very
probable to be found in XFree86 sources.
<br><br><li><b><font size=+2>indexed color mode</font></b></li>
<p>This might work, however I have not tested it yet. glutGetColor/glutSetColor is not
implemented. Again, looks like a single Xlib call, but there might be some problems
with the colormap access. Need to switch into indexed color mode some day and check it
out (does Mesa 3.1 work with indexed color mode?)
<br><br><li><b><font size=+2>planes</font></b></li>
<p>Overlays are not supported, but one of the GLUT conformance tests fails due to
glutLayerGet( GLUT_NORMAL_DAMAGED ) returning FALSE when the window has actually
been damaged.
<p>Layers would be good for drawing the menus and mouse cursor, as they wouldn't force
the application redraw to update their state.
<br><br><li><b><font size=+2>init display string</font></b></li>
<p>I am in middle of the fight with the init display string. It's parsing OK, now it
would be cool to make it impress some effects on the display...
<br><br><li><b><font size=+2>game mode</font></b></li>
<p>Is the game mode string parsed correctly?
<br><br><li><b><font size=+2>geometry</font></b></li>
<p>Andreas Umbach has contributed the cube and sphere code. The teapot rendering is
done using free SGI code. I have also added the cone rendering, however it is missing
normal vectors (just as Andrea's wireframed cube does). All of the glut*hedron()
functions await to be implemented.
<br><br><li><b><font size=+2>obvious bugs</font></b></li>
<br><br><ol>
<li>
the visibility/window status function is a conceptual mess. I had to peer into the GLUT
source code to see what actually happens inside. It helped me a bit, but still one of
the visibility tests fails. This is probably the reason for which a window covered by
enlightenment status bar is marked as hidden and does not get redrawn.</li>
<li>
GLX 1.3 spec states that glXChooseVisual() et consortes are deprecated. Should move to
glXFBConfig.</li>
<li>
need to investigate what happens when initial window position is set to (-1,-1). GLUT
specification says, that the window positioning should be left to the window system.
And I do not know how to force it do so...</li>
<li>
I was told it is wrong to have the redisplay forced in the main loop. Is that right?</li>
</ol><br><li><b><font size=+2>not so obvious bugs</font></b></li>
<br><br><ol>
<li>some of the tests freeze because they do not generate the glutPostRedisplay() call
every frame. Again, this is somehow handled by GLUT, but I can't see how. And why.
<p>Looks like I've fixed it (or rather hacked it?) by forcing a redisplay every
frame, but this is no good and kills interactiveness of my console :D</li>
</ol></ul>
<a href="index.html"><i>Back to the main page</i></a>
</table></center></body></html>

View File

@ -0,0 +1,80 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="author" content="Pawel W. Olszta">
<meta name="copyright" content="Pawel W. Olszta">
<meta name="description" content="The freeglut project plans">
<meta name="keywords" content="freeglut glut OpenGL">
<meta name="GENERATOR" content="WebMaker">
<title>The freeglut project</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<center><img SRC="freeglut_logo.png" ALT="The freeglut logo" height=106 width=314></center>
<center><dt><i><font face="Courier New,Courier"><font size=+1>
I've got a master plan (to take your API down)...
</font></font></i></dt></center>
<center><table WIDTH="620" ><tr><td><hr WIDTH="100%">
<p>After that I get the freeglut Windows port working in an acceptable manner and thus
getting assured that the freeglut internal structure is valid, I will split the project
into three separate parts, listed below.
<br><ul><li><b><font size=+2>freeglut-common</font></b></li>
<p>The least common denominator between the two freeglut versions. This will probably
contain most of the internal structure of the toolkit, notably the windows and menu
hierarchy, and possibly some private helpers.
<br><br><li><b><font size=+2>freeglut-1.3</font></b></li>
<p>The GLUT API 3 compatible library. This is what's can be found now in the alpha
release (apart from the bugs, naturally :D).
<br><br><li><b><font size=+2>freeglut-2.0</font></b></li>
<p>Hopefully this will be what GLUT should have been from the beginning. I will give
a try to design a much more coherent API than GLUT's, aiming at fast games prototyping.
<a href="mailto:olszta@sourceforge.net">Suggestions</a> are welcome.</ul>
<br><p>Here's a list of propositions I have received so far. Hopefully this some day
turns into an API spefication proposal, not just a bunch of meaningless phrases...<br>
<br><li>glutBitmapHeight() and glutStrokeHeight() -- I have added them to the
freeglut-1.3 API, they are already implemented and should work fine,</li>
<br><li>glutBitmapString() and glutStrokeString(), to write (multiple-line maybe)
strings, starting from the current raster position, using some simple formatting
maybe (changing the color, font, etc.?)</li>
<br><li>texture mapped fonts -- this is easy and could be added to freeglut-1.3, but
would require adding the...</li>
<br><li>glutHint() function to tell freeglut to: use bitmapped/texture mapped fonts,
draw the menus and mouse cursor using OpenGL/window system, and stuff...</li>
<br><li>glutMainLoop() termination and glutMainLoopStep() function, which should
perform a single check of pending events, so that one can have his own main loop,</li>
<br><li>multiple joysticks support with multiple axes, buttons, hats, etc. It is a real
good thing to do, yet the API to do the magic might result in being really twisted,</li>
<br><li>glutModifierFunc() could be added, or glutGetModifierState() should be allowed
to be called anywhere from the client's code</li>
<br><p>We might also think about:<br>
<br><li>freeglut-2.0 modularity via plugins, so that only the features that one
needs get loaded (plugins are easily supported by GLib),</li>
<br><li>OpenGL state management functions,</li>
<br><li>audio support -- using OpenAL maybe?,</li>
<br><li>a real menu system, not only the popups</li>
<br><li>non-OpenGL but portable UI, something like Java Swing</li>
<br><li>window-closing confirmation box (this is related to the above)</li>
<br><p>Following ideas are bad for freeglut:<br>
<br><li>more accurate timers under Win32 -- this goes to the GLib development afaik</li>
<br><li>portable file I/O, portable threads, plugins/modules -- this is already
done in GLib</li>
<br><br><a href="index.html"><i>Back to the main page</i></a>
</table></center></body></html>