Initial revision

git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@3 232f8b59-042b-4e1e-8c03-345bb8c30851
author: djp <[email protected]> 2003-06-08 19:27:01 +0000
committer: djp <[email protected]> 2003-06-08 19:27:01 +0000
commit: d49fd968963909f181423eae46c613189468fac3 (patch)
tree: b231329e6b65fd54aa24b3bcc0a3ecc623daec61 /doc
parent: 9c8fb046dee5d832bea3f36dcbd43285054f49a0 (diff)
3 files changed, 141 insertions, 0 deletions
diff --git a/doc/HowToBuild.html b/doc/HowToBuild.html
new file mode 100644
index 000000000..73a4a943e
--- /dev/null
+++ b/doc/HowToBuild.html
@@ -0,0 +1,51 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+<head>
+<title>How to build the Jogl OpenGL binding for Java</title>
+</head>
+<body>
+
+<h1>How to build the Jogl OpenGL binding for Java</h1>
+<hr>
+
+Here are the steps that are required in order to build the Jogl
+OpenGL binding from a fresh copy of the source distribution:
+
+<OL>
+  <LI> <B>Install ANTLR:</B> <br> Download and unpack ANTLR 2.7.2 from <a href="http://www.antlr.org">http://www.antlr.org</a>. 
+
+  <LI> <B>Set your CLASSPATH environment variable:</B> <br> Add the ANTLR jar file to your classpath.
+
+  <LI> <B>Set the JAVA_HOME environment variable:</B> <br> Create an environment variable named JAVA_HOME and set it to point to the root of your Java SDK.
+
+  <LI> <B>Install GNU Make:</B> To confirm that it is installed, run "make -v"; you should see some output that starts with "GNU Make version" and then a version number. 
+      <UL>
+	<LI><b>On Linux/Solaris:</b> Gnu Make is probably already installed. If it is not, you can obtain it from <a href="http://www.gnu.org/directory/devel/build/make.html">http://www.gnu.org/directory/devel/build/make.html</a>
+	<LI><b>On Win32:</b> You have two options. The first is to install the Cygwin environment, available from <a href="http://www.cygwin.com/">http://www.cygwin.com/</a>. The second (untested) option is to install the GnuWin32 tools, available from <a href="http://sourceforge.net/projects/gnuwin32/"</a>http://sourceforge.net/projects/gnuwin32/</a>.
+      </UL>
+  <LI> <B>Build the source tree:</B> <br> You can do this by opening a command shell in the "make" directory of the source tree and typing "make PLATFORM COMPILER_OPTIONS CG_OPTIONS". PLATFORM, COMPILER_OPTIONS and CG_OPTIONS are as follows:
+      <UL>
+	<LI><b>PLATFORM</b> This must be one of "win32", "x11", or "macosx". "win32" will build the code for 32-bit Microsoft Windows operating systems, "x11" will build for Linux or Sun Solaris, and "macosx" will build for Apple MacOS X.  
+	<LI><b>COMPILER_OPTIONS</b> This is currently only needed when "win32" is specified. COMPILER_OPTIONS must be one of "VC6=1" or "VC7=1"; choosing the former will invoke the Microsoft Visual C++ 6.0 compiler, and the latter option will invoke the Microsoft Visual C++ 7 (Visual Studio .NET) compiler. These are the two compilers currently supported by Jogl on Win32. 
+	<LI><b>CG_OPTIONS</b> A value of "CG=1" will generate an experimental binding for the Cg language runtime by NVidia Corporation. As of this writing the Cg binding was only supported on the Windows platform.
+      </UL>
+      
+  <LI> <B>Add Jogl to your CLASSPATH:</B> <br> To be able to use Jogl, you must add the build process Java bytecode output directory (<source tree root>/build/classes) to your CLASSPATH environment variable.
+  <LI> <B>Add Jogl to your PATH:</B> <br> To be able to use Jogl, you must also add the build process JNI code library directory (<source tree root>/build/obj) to your PATH.
+  <LI> <B>Test if everything's working:</B> <br> To test if everything went well, you should build the "Gears.java" demo in the "<source tree root>/demos/gears" directory. Run "javac Gears.java" and then "java Gears"; you should see some spinning 3D gears appear in a window. 
+  <LI> <B>Build Javadoc:</B> <br> "make doc" will produce the end-user documentation for Jogl along with some auxiliary utility packages. "make devdoc" will produce the developers' documentation, including that for the GlueGen tool. Appending "CG=1" to either of these commands will cause the javadoc for the Cg binding to be generated.
+</OL>
+ 
+Note that there are a lot of warnings produced by ANTLR about the 
+C grammar and our modifications to some of the signatures of the 
+productions; the C grammar warnings have been documented by the 
+author of the grammar as having been investigated completely and 
+harmless, and the warnings about our modifications are also 
+harmless. <P>
+
+- Christopher Kline and Kenneth Russell, June 2003
+
+
+
+</body>
+</html>
diff --git a/doc/TODO.txt b/doc/TODO.txt
new file mode 100644
index 000000000..c27bebc32
--- /dev/null
+++ b/doc/TODO.txt
@@ -0,0 +1,78 @@
+
+-----------------
+  HIGH PRIORITY
+-----------------
+
+- Correct sharing of data (display lists, texture objects) between
+  contexts. This is different for X vs W32 -- one can be done at
+  runtime, the other requires sharing to be done at context creation.
+  For Win32, see the wglShareLists(). For a GLX platform, see the
+  share parameter to glXCreateContext().
+
+
+- Non-const array types must be properly released with JNI_COMMIT in
+  order to see side effects if the array was copied.
+
+- Finish implementation of <type>** arguments (currently only works
+  for "const char**". This is needed for glMultiDrawElements and
+  one Cg routine.
+
+-----------------
+ MEDIUM PRIORITY
+-----------------
+
+- Figure out how to implement GLEventListener.displayChanged(bool,bool). 
+  I believe we need additional support in J2SE before this will be possible
+  to detect and implement. The basic problem is that we need to find a way 
+  to determine when a GLCanvas has moved to a different
+  display device, so we can re-load the GL function addresses using
+  wgl/glXGetProcAddress. See comments at top of GLCanvas.java. Also need a
+  way to determine with the display mode (e.g., bit depth) of the GLDrawable
+  has changed. Once both of these problems are solved, we'll need to hook it
+  into GLEventListener.displayChanged() and also be sure to reset the
+  GLDrawable's glProcAddress table as appropriate.
+
+-----------------
+ LOW PRIORITY
+-----------------
+
+- Think about making StructAccessors for e.g. GLUquadric "more opaque"
+
+- Think about e.g. protected access for Impl classes
+
+- Find a way to limit the expansion of void* types to only certain
+  java array types. For example, glCallLists(..., GLenum type, void*)
+  only accepts certain values in its type parameter; it would be nice
+  to limit the expansion to those types.
+
+- Fix glProgramStringARB and glGetProgramString{NV,ARB} so that they
+  use Strings and/or StringBuffers insteead of GLUbyte* and void*
+
+- figure out how to deal with WGL entry points:
+    WINGDIAPI HGLRC WINAPI wglCreateLayerContext(HDC, int);
+    WINGDIAPI BOOL  WINAPI wglUseFontBitmapsA(HDC, DWORD, DWORD, DWORD);
+    WINGDIAPI BOOL  WINAPI wglUseFontBitmapsW(HDC, DWORD, DWORD, DWORD);
+  see commented-out section in make/stub_includes/win32/wingdi.h
+
+- Need a disciplined mechanism for converting char* argument types. For
+  example, many C functions accept a "char*" argument with the semantic that
+  output data will be written into the buffer pointed to by the
+  argument. The type "const char*" is used when the argument's data will be
+  unchanged. Our system needs a new directive, such as
+  "ArgumentIsStringBuffer" to be used for type conversion in those cases
+  where the native code needs to write output into the "char*" argument. Not
+  sure how to handle this on the native side -- it may require hints to the
+  native code generator as to how large the StringBuffer's backing buffer
+  needs to be, so we can assert this condition before passing the backing
+  buffer to the C function we are wrapping.
+
+- Throw an exception if native calls to GetPrimitiveArrayCritical
+  return null.
+
+- Before emitting functions and constants, sort them first by
+  extension suffix (i.e., ARB, ATI, NV, etc) and then by name. This
+  will organize them in the file more logically. When writing the
+  code, the sort function can check the last substring that's all caps,
+  and treat this as the extension owner. Be careful though, some end
+  in "3D" and that's not an extension.
+
diff --git a/doc/differences-from-gl4java.txt b/doc/differences-from-gl4java.txt
new file mode 100644
index 000000000..9114c89cf
--- /dev/null
+++ b/doc/differences-from-gl4java.txt
@@ -0,0 +1,12 @@
+- GLContext is no longer exposed in the public API.
+- No more GLAnimCanvas/GLAnimJPanel variants. To perform animation,
+  attach an Animator to a GLDrawable.
+- No GLEnum class. Use GL.[GL_CONSTANT_NAME].
+- GLFunc/GLFunc14 are named GL.
+- GLUFunc/GLUFunc14 are named GLU.
+- Drawable factory does not take initial width and height of drawable.
+- GLEventListener.reshape() now takes x and y arguments, though these
+  should usually be ignored by the application.
+- Simpler GLEventListener API; preDisplay and postDisplay have been
+  removed. GLEventListener.cleanup is not yet supported as it is not
+  clear what the semantics of this routine should be.
author	djp <[email protected]>	2003-06-08 19:27:01 +0000
committer	djp <[email protected]>	2003-06-08 19:27:01 +0000
commit	d49fd968963909f181423eae46c613189468fac3 (patch)
tree	b231329e6b65fd54aa24b3bcc0a3ecc623daec61 /doc
parent	9c8fb046dee5d832bea3f36dcbd43285054f49a0 (diff)