summaryrefslogtreecommitdiffstats
path: root/doc/manual
diff options
context:
space:
mode:
authorKenneth Russel <[email protected]>2006-02-05 18:09:23 +0000
committerKenneth Russel <[email protected]>2006-02-05 18:09:23 +0000
commit875652cab75b68ac30b9b1cc81ee62f7ff1e165d (patch)
tree7e6d85cee9453f6864d9067ac1c90213244ab4e0 /doc/manual
parent98da87017cb72785ca13f5b0657ce2c5d8a067c3 (diff)
Intermediate checkin for FBO support in Java2D/JOGL bridge. Needed to
keep track of server-side OpenGL objects, like textures and display lists, created by the end user to preserve the illusion of independent contexts even though they will all share textures and display lists with the Java2D OpenGL context in order to access its FBO. Added GLObjectTracker class to track creation and destruction of these objects and to support cleanup when the last referring context has been destroyed. Modified GLContextShareSet to create and install GLObjectTrackers when necessary and GLContext to ref and unref tracker appropriately. Changed GlueGen's JavaPrologue and JavaEpilogue directives (and their documentation) to perform argument name substitution. Wrote documentation section on argument name substitution and specified behavior for primitive arrays (converts to string "array_name, array_name_offset" in substitution). Rephrased GlueGen's RangeCheck directives in terms of JavaPrologue directives and deleted old specialized code. Fixed bug in handling of VBO support in GLConfiguration when JavaPrologue was present for affected functions. Added JavaPrologue and JavaEpilogue directives to all existing OpenGL routines creating server-side objects (though it's possible some were missed) to call GLObjectTracker when necessary. Added RangeCheck directives for these routines as well. Worked around bug in JOGL demos where shutdownDemo() was being called more than once. git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/../svn-server-sync/gluegen/trunk@13 a78bb65f-1512-4460-ba86-f6dc96a7bf27
Diffstat (limited to 'doc/manual')
-rwxr-xr-xdoc/manual/index.html102
1 files changed, 86 insertions, 16 deletions
diff --git a/doc/manual/index.html b/doc/manual/index.html
index 2e4ed84..cbeea8e 100755
--- a/doc/manual/index.html
+++ b/doc/manual/index.html
@@ -1,3 +1,9 @@
+<HTML>
+<HEAD>
+<TITLE>GlueGen Manual</TITLE>
+</HEAD>
+<BODY>
+
<H1>GlueGen Manual</H1>
<H2> Table of Contents </H2>
@@ -23,6 +29,7 @@ Chapter 2 - Using GlueGen
<LI> <a href = "#SecStub">Stub Headers</a>
<LI> <a href = "#Sec32">32- and 64-bit Considerations</a>
<LI> <a href = "#SecOpaque">Opaque Directives</a>
+<LI> <a href = "#SecSubstitution">Argument Name Substitution</a>
<LI> <a href = "#SecConfiguration">Configuration File Directives</a>
<UL>
<LI> <a href = "#SecJavaEmitter">JavaEmitter Configuration</a>
@@ -755,6 +762,63 @@ type to a Java long:
Now HANDLEs are exposed to Java as longs as desired. A similar
technique is used to expose XIDs on the X11 platform as Java longs.
+</P>
+
+
+<H3><a name="SecSubstitution">Argument Name Substitution</a></H3>
+
+<P>
+
+Certain configuration file directives allow the insertion of Java or C
+code at various places in the generated glue code, to both eliminate
+the need to hand-edit the generated glue code as well as to minimize
+the hand-writing of glue code, which sidesteps the GlueGen process. In
+some situations the inserted code may reference incoming arguments to
+compute some value or perform some operation. Examples of directives
+supporting this substitution include <a
+href="#ReturnValueCapacity">ReturnValueCapacity</a> and <a
+href="#ReturnedArrayLength">ReturnedArrayLength</a>.
+
+</P>
+<P>
+
+The expressions in these directives may contain Java MessageFormat
+expressions like <code>{0}</code> which refer to the incoming argument
+names to the function. <code>{0}</code> refers to the first incoming
+argument.
+
+</P>
+<P>
+
+Strongly-typed C primitive pointers such as <code>int*</code>, which
+ordinarily expand to overloaded Java methods taking
+e.g. <code>int[]</code> as well as <code>IntBuffer</code>, present a
+problem. The expansion to <code>int[] arr</code> also generates an
+<code>int arr_offset</code> argument to be able to pass a pointer into
+the middle of the array down to C. To allow the same MessageFormat
+expression to be used for both cases, the subsitution that occurs when
+such a primitive array is referenced is the string <code>arr,
+arr_offset</code>; in other words, the subtituted string contains a
+comma. This construct may be used in the following way: the code being
+manually inserted may itself contain a method call taking
+e.g. <code>{3}</code> (the incoming argument index of the primitive
+array or buffer). The user should supply two overloaded versions of
+this method, one taking a strongly-typed Buffer and one taking e.g. an
+<code>int[] arr</code> and <code>int arr_offset</code> argument. The
+implementation of <code>RangeCheck</code>s for primitive arrays and
+strongly-typed buffers uses this construct.
+
+</P>
+<P>
+
+It should be noted that in the autogenerated C code the offset
+argument is expressed in bytes while at the Java level it is expressed
+in elements. Most uses of GlueGen will probably not have to refer to
+the primitive array arguments in C code so this slight confusion
+should be minor.
+
+</P>
+
<H3><a name="SecConfiguration">Configuration File Directives</a></H3>
@@ -1047,10 +1111,11 @@ href="#ImplJavaClass">ImplJavaClass</a>.
(optional) Adds the specified code as an epilogue in the Java method
for the specified C function; this code is run after the underlying C
function has been called via the native method but before any result
-is returned. No transformations are currently performed on this code,
-unlike in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a>
-and other directives. See also <a
-href="#JavaPrologue">JavaPrologue</a>.
+is returned. As in the <a
+href="#ReturnedArrayLength">ReturnedArrayLength</a> and other
+directives, <a href="#SecSubstitution">argument name
+substitution</a> is performed on MessageFormat expressions in the
+specified code. See also <a href="#JavaPrologue">JavaPrologue</a>.
<dt><strong><a name="JavaOutputDir">JavaOutputDir</a></strong>
@@ -1068,10 +1133,11 @@ defaults to the current working directory.
(optional) Adds the specified code as a prologue in the Java method
for the specified C function; this code is run before the underlying C
-function is called via the native method. No transformations are
-currently performed on this code, unlike in the <a
+function is called via the native method. As in the <a
href="#ReturnedArrayLength">ReturnedArrayLength</a> and other
-directives. See also <a href="#JavaEpilogue">JavaEpilogue</a>.
+directives, <a href="#SecSubstitution">argument name
+substitution</a> is performed on MessageFormat expressions in the
+specified code. See also <a href="#JavaEpilogue">JavaEpilogue</a>.
<dt><strong><a name="ManuallyImplement">ManuallyImplement</a></strong>
@@ -1160,9 +1226,8 @@ that should be expressed in terms of a number of bytes rather than a
number of elements, see the <a
href="#RangeCheckBytes">RangeCheckBytes</a> directive. As in the <a
href="#ReturnedArrayLength">ReturnedArrayLength</a> and other
-directives, MessageFormat expressions such as "{0}" are replaced with
-the corresponding incoming argument name, where the first incoming
-argument is index 0.
+directives, <a href="#SecSubstitution">argument name substitution</a>
+is performed on MessageFormat expressions.
<dt><strong><a name="RangeCheckBytes">RangeCheckBytes</a></strong>
@@ -1171,7 +1236,8 @@ argument is index 0.
(optional) Same as the <a href="#RangeCheck">RangeCheck</a> directive,
but the specified expression is treated as a minimum number of bytes
-remaining rather than a minimum number of elements remaining.
+remaining rather than a minimum number of elements remaining. This
+directive may not be used with primitive arrays.
<dt><strong><a name="RenameJavaMethod">RenameJavaMethod</a></strong>
@@ -1203,7 +1269,8 @@ href="#ImplJavaClass">ImplJavaClass</a> directives.
expression with MessageFormat specifiers such as "{0}". These
specifiers will be replaced in the generated glue code with the
incoming argument names where the first argument to the method is
-numbered 0. <br>
+numbered 0. See the section on <a href="#SecSubstitution"> argument
+name substitution</a>.<br>
(optional) For a function returning a compound C pointer type such as
an <code>XVisualInfo*</code>, indicates that the returned pointer is
@@ -1235,8 +1302,8 @@ subclass wrapping a C primitive pointer such as <code>char*</code> or
<code>float*</code> being returned from a C function. Typically
necessary in order to properly use such pointer return results from
Java. As in the <a href="#ReturnedArrayLength">ReturnedArrayLength</a>
-directive, argument name substitution is performed on MessageFormat
-expressions such as "{0}" where the first argument is index 0.
+directive, <a href="#SecSubstitution">argument name substitution</a>
+is performed on MessageFormat expressions.
<dt><strong><a name="ReturnValueLength">ReturnValueLength</a></strong>
@@ -1253,8 +1320,8 @@ directive handles boxing of individual elements of the array (which
are pointers) in to the Java class which wraps that C struct type. See
the (FIXME) examples for a concrete example of usage. As in the <a
href="#ReturnedArrayLength">ReturnedArrayLength</a> directive,
-argument name substitution is performed on MessageFormat expressions
-such as "{0}" where the first argument is index 0.
+<a href="#SecSubstitution">argument name substitution</a> is performed
+on MessageFormat expressions.
<dt><strong><a name="RuntimeExceptionType">RuntimeExceptionType</a></strong>
@@ -1538,3 +1605,6 @@ despite the fact that it has an associated function pointer typedef in
the header.
</dl>
+
+</BODY>
+</HTML>